Zabalení a nasazení prostředků v aplikacích .NET

Článek
12/21/2023

Aplikace spoléhají na Správce prostředků rozhraní .NET Framework reprezentované ResourceManager třídou k načtení lokalizovaných prostředků. Resource Manager předpokládá, že se k balení a nasazení prostředků používá hvězdicový model. Centrum je hlavní sestavení, které obsahuje nelokalizovatelný spustitelný kód a prostředky pro jednu jazykovou verzi, označované jako neutrální nebo výchozí jazyková verze. Výchozí jazyková verze je záložní jazyková verze aplikace; je to jazyková verze, jejíž prostředky se používají, pokud lokalizované prostředky nelze najít. Každý paprsk se připojuje k satelitnímu sestavení, které obsahuje prostředky pro jednu jazykovou verzi, ale neobsahuje žádný kód.

Tento model má několik výhod:

Po nasazení aplikace můžete postupně přidávat prostředky pro nové jazykové verze. Vzhledem k tomu, že následný vývoj prostředků specifických pro jazykovou verzi může vyžadovat značné množství času, můžete nejprve vydat hlavní aplikaci a dodávat prostředky specifické pro jazykovou verzi později.
Můžete aktualizovat a změnit satelitní sestavení aplikace bez opětovného zkompilování aplikace.
Aplikace musí načíst pouze satelitní sestavení, která obsahují prostředky potřebné pro konkrétní jazykovou verzi. To může výrazně snížit využití systémových prostředků.

Tento model má ale také nevýhody:

Musíte spravovat více sad prostředků.
Počáteční náklady na testování aplikace se zvyšují, protože je nutné otestovat několik konfigurací. Mějte na paměti, že v dlouhodobém horizontu bude jednodušší a levnější testovat jednu základní aplikaci s několika satelity, než testovat a udržovat několik paralelních mezinárodních verzí.

Zásady vytváření názvů prostředků

Když zabalíte prostředky aplikace, musíte je pojmenovat pomocí konvencí pojmenování prostředků, které modul CLR (Common Language Runtime) očekává. Modul runtime identifikuje prostředek podle názvu jazykové verze. Každá jazyková verze má jedinečný název, což je obvykle kombinace dvoumísmenného názvu jazykové verze přidruženého k jazyku a v případě potřeby dvoumísmenného názvu subculture přidruženého k zemi nebo oblasti. Název subculture se řídí názvem jazykové verze oddělené pomlčkou (-). Příklady zahrnují ja-JP pro japonštinu, jak mluví v Japonsku, en-US pro angličtinu, jak mluví v USA, de-DE pro němčinu, jak mluví v Německu, nebo de-AT pro němčinu, jak mluví v Rakousku. Podívejte se na sloupec Značka jazyka v seznamu názvů jazyků a oblastí podporovaných systémem Windows. Názvy jazykových verzí se řídí standardem definovaným BCP 47.

Poznámka:

Existují některé výjimky pro názvy dvoumísmenné jazykové verze, například zh-Hans pro čínštinu (zjednodušená).

Další informace naleznete v tématu Vytvoření souborů prostředků a Vytvoření satelitních sestavení.

Záložní proces prostředku

Hvězdicový model pro balení a nasazování prostředků používá náhradní proces k vyhledání vhodných prostředků. Pokud aplikace požaduje lokalizovaný prostředek, který není k dispozici, modul CLR (Common Language Runtime) vyhledá v hierarchii jazykových verzí odpovídající záložní prostředek, který nejvíce odpovídá požadavku aplikace uživatele, a vyvolá výjimku pouze jako poslední možnost. Pokud se najde vhodný prostředek, modul runtime ho použije na každé úrovni hierarchie. Pokud se prostředek nenajde, bude hledání pokračovat na další úrovni.

Pokud chcete zlepšit výkon vyhledávání, použijte NeutralResourcesLanguageAttribute atribut na hlavní sestavení a předejte ho název neutrálního jazyka, který bude fungovat s hlavním sestavením.

Proces náhradního prostředku rozhraní .NET Framework

Proces náhradního prostředku rozhraní .NET Framework zahrnuje následující kroky:

Tip

Je možné, že budete moct použít <element konfigurace relativeBindForResources> k optimalizaci záložního procesu prostředku a procesu, podle kterého modul runtime sonduje sestavení prostředků. Další informace naleznete v tématu Optimalizace záložního procesu prostředku.

Modul runtime nejprve zkontroluje globální mezipaměť sestavení pro sestavení, které odpovídá požadované jazykové verzi vaší aplikace.

Globální mezipaměť sestavení může ukládat sestavení prostředků, která jsou sdílena mnoha aplikacemi. To vám umožní zahrnout konkrétní sady prostředků do adresářové struktury každé aplikace, kterou vytvoříte. Pokud modul runtime najde odkaz na sestavení, vyhledá sestavení požadovaný prostředek. Pokud najde položku v sestavení, použije požadovaný prostředek. Pokud položku nenajde, bude pokračovat v hledání.
Modul runtime dále zkontroluje adresář aktuálně spuštěného sestavení pro podadresář, který odpovídá požadované jazykové verzi. Pokud najde podadresář, vyhledá tento podadresář platné satelitní sestavení pro požadovanou jazykovou verzi. Modul runtime pak prohledá satelitní sestavení požadovaného prostředku. Pokud prostředek najde v sestavení, použije ho. Pokud prostředek nenajde, bude pokračovat ve vyhledávání.
Modul runtime dále dotazuje Instalační službu systému Windows, aby určila, zda je satelitní sestavení nainstalováno na vyžádání. Pokud ano, zpracuje instalaci, načte sestavení a vyhledá ho nebo požadovaný prostředek. Pokud prostředek najde v sestavení, použije ho. Pokud prostředek nenajde, bude pokračovat ve vyhledávání.
Modul runtime vyvolá událost, která indikuje AppDomain.AssemblyResolve , že nemůže najít satelitní sestavení. Pokud se rozhodnete zpracovat událost, může obslužná rutina události vrátit odkaz na satelitní sestavení, jehož prostředky budou použity pro vyhledávání. V opačném případě se obslužná rutina události vrátí null a hledání pokračuje.
Modul runtime příště znovu prohledá globální mezipaměť sestavení, tentokrát pro nadřazené sestavení požadované jazykové verze. Pokud nadřazené sestavení existuje v globální mezipaměti sestavení, modul runtime prohledá sestavení požadovaného prostředku.

Nadřazená jazyková verze je definována jako vhodná záložní jazyková verze. Zvažte rodiče jako náhradní kandidáty, protože poskytnutí jakéhokoli prostředku je vhodnější vyvolat výjimku. Tento proces také umožňuje opakovaně používat prostředky. Konkrétní prostředek byste měli zahrnout na nadřazené úrovni pouze v případě, že podřízená jazyková verze nepotřebuje lokalizovat požadovaný prostředek. Pokud například zadáte satelitní sestavení pro en (neutrální angličtinu), en-GB (angličtinu jako mluvený ve Spojeném království) a en-US (v USA se mluví anglicky), en bude satelit obsahovat společnou terminologii a en-GBen-US satelity můžou poskytovat přepsání pouze pro ty výrazy, které se liší.
Modul runtime dále zkontroluje adresář aktuálně spuštěného sestavení a zjistí, jestli obsahuje nadřazený adresář. Pokud existuje nadřazený adresář, modul runtime vyhledá v adresáři platné satelitní sestavení pro nadřazenou jazykovou verzi. Pokud sestavení najde, modul runtime vyhledá sestavení požadovaného prostředku. Pokud prostředek najde, použije ho. Pokud prostředek nenajde, bude pokračovat ve vyhledávání.
Modul runtime dále dotazuje Instalační službu systému Windows, aby určila, zda má být nadřazené satelitní sestavení nainstalováno na vyžádání. Pokud ano, zpracuje instalaci, načte sestavení a vyhledá ho nebo požadovaný prostředek. Pokud prostředek najde v sestavení, použije ho. Pokud prostředek nenajde, bude pokračovat ve vyhledávání.
Modul runtime vyvolá událost, která indikuje AppDomain.AssemblyResolve , že nemůže najít vhodný záložní prostředek. Pokud se rozhodnete zpracovat událost, může obslužná rutina události vrátit odkaz na satelitní sestavení, jehož prostředky budou použity pro vyhledávání. V opačném případě se obslužná rutina události vrátí null a hledání pokračuje.
Modul runtime dále prohledá nadřazená sestavení, stejně jako v předchozích třech krocích, prostřednictvím mnoha potenciálních úrovní. Každá jazyková verze má pouze jeden nadřazený objekt, který je definován vlastností CultureInfo.Parent , ale nadřazený objekt může mít svůj vlastní nadřazený objekt. Hledání nadřazených jazykových verzí se zastaví, když se vrátí CultureInfo.InvariantCulturevlastnost jazykové verze Parent ; pro záložní prostředek se invariantní jazyková verze nepovažuje za nadřazenou jazykovou verzi nebo jazykovou verzi, která může obsahovat prostředky.
Pokud byla původně zadaná jazyková verze a všechny nadřazené položky byly prohledávané a prostředek se stále nenajde, použije se prostředek pro výchozí (záložní) jazykovou verzi. Prostředky pro výchozí jazykovou verzi jsou obvykle zahrnuty do hlavního sestavení aplikace. Můžete však zadat hodnotu Satellite vlastnosti Location NeutralResourcesLanguageAttribute atributu, která označuje, že konečným záložním umístěním pro prostředky je satelitní sestavení, nikoli hlavní sestavení.

Poznámka:

Výchozí prostředek je jediný prostředek, který lze zkompilovat pomocí hlavního sestavení. Pokud nezadáte satelitní sestavení pomocí atributu NeutralResourcesLanguageAttribute , je to konečný záložní (konečný nadřazený). Proto doporučujeme, abyste do hlavního sestavení vždy zahrnuli výchozí sadu prostředků. To pomáhá zabránit vyvolání výjimek. Když zahrnete výchozí prostředek, poskytnete záložní soubor pro všechny prostředky a zajistíte, aby pro uživatele vždy byl alespoň jeden prostředek, i když není kulturní.
A konečně, pokud modul runtime nenajde prostředek pro výchozí (záložní) jazykovou verzi, MissingManifestResourceException vyvolá se chyba nebo MissingSatelliteAssemblyException výjimka, která značí, že se prostředek nepodařilo najít.

Předpokládejme například, že aplikace požaduje prostředek lokalizovaný pro španělštinu (Mexiko) (jazykovou es-MX verzi). Modul runtime nejprve vyhledá globální mezipaměť sestavení pro sestavení, která odpovídá es-MX, ale nenajde ji. Modul runtime pak prohledá adresář aktuálně spuštěného sestavení pro es-MX adresář. Pokud se to nepodaří, modul runtime znovu vyhledá globální mezipaměť sestavení pro nadřazené sestavení, které odráží příslušnou záložní jazykovou verzi – v tomto případě es (španělština). Pokud nadřazené sestavení není nalezeno, modul runtime vyhledá všechny potenciální úrovně nadřazených sestavení pro jazykovou es-MX verzi, dokud nenajde odpovídající prostředek. Pokud se prostředek nenajde, modul runtime použije prostředek pro výchozí jazykovou verzi.

Optimalizace záložního procesu prostředků rozhraní .NET Framework

Za následujících podmínek můžete optimalizovat proces, podle kterého modul runtime hledá prostředky v satelitních sestaveních:

Satelitní sestavení jsou nasazena ve stejném umístění jako sestavení kódu. Pokud je sestavení kódu nainstalováno v globální mezipaměti sestavení, satelitní sestavení jsou také nainstalována v globální mezipaměti sestavení. Pokud je sestavení kódu nainstalováno v adresáři, satelitní sestavení jsou nainstalována ve složkách specifických pro jazykovou verzi tohoto adresáře.
Satelitní sestavení nejsou nainstalovaná na vyžádání.
Kód aplikace nezpracuje AppDomain.AssemblyResolve událost.

Sondu pro satelitní sestavení optimalizujete zahrnutím elementu <relativeBindForResources> a nastavením jeho enabled atributu do true konfiguračního souboru aplikace, jak je znázorněno v následujícím příkladu.

<configuration>
   <runtime>
      <relativeBindForResources enabled="true" />
   </runtime>
</configuration>

Optimalizovaná sonda pro satelitní sestavení je funkce výslovného souhlasu. To znamená, že modul runtime se řídí kroky zdokumentované v záložním procesu prostředku, pokud <není v konfiguračním souboru aplikace k dispozici relativeBindForResources> element a jeho enabled atribut je nastaven na true. V takovém případě se proces sondování satelitního sestavení upraví takto:

Modul runtime používá umístění nadřazeného sestavení kódu k sondě pro satelitní sestavení. Pokud je nadřazené sestavení nainstalováno v globální mezipaměti sestavení, sondy modulu runtime v mezipaměti, ale ne v adresáři aplikace. Pokud je nadřazené sestavení nainstalováno v adresáři aplikace, modul runtime sondy v adresáři aplikace, ale ne v globální mezipaměti sestavení.
Modul runtime se dotazuje instalační služby systému Windows na instalaci satelitních sestavení na vyžádání.
Pokud sonda pro konkrétní sestavení prostředků selže, modul runtime událost nevyvolá AppDomain.AssemblyResolve .

Proces náhradního prostředku .NET Core

Proces náhradního prostředku .NET Core zahrnuje následující kroky:

Modul runtime se pokusí načíst satelitní sestavení pro požadovanou jazykovou verzi.
- Zkontroluje adresář aktuálně spuštěného sestavení pro podadresář, který odpovídá požadované jazykové verzi. Pokud najde podadresář, vyhledá tento podadresář platné satelitní sestavení požadované jazykové verze a načte ho.
  
  Poznámka:
  
  V operačníchsystémechch Název podadresáře se musí přesně shodovat s písmenem CultureInfo.Name (napříklades).es-MX
  
  Poznámka:
  
  Pokud programátor odvozuje vlastní kontext načtení sestavení z AssemblyLoadContext, situace je složitá. Pokud bylo spuštěné sestavení načteno do vlastního kontextu, modul runtime načte satelitní sestavení do vlastního kontextu. Podrobnosti jsou mimo rozsah tohoto dokumentu. Viz třída AssemblyLoadContext.
- Pokud satelitní sestavení nebylo nalezeno, AssemblyLoadContext vyvolá událost, která indikuje AssemblyLoadContext.Resolving , že nemůže najít satelitní sestavení. Pokud se rozhodnete zpracovat událost, může obslužná rutina události načíst a vrátit odkaz na satelitní sestavení.
- Pokud satelitní sestavení stále nebylo nalezeno, AssemblyLoadContext způsobí, že AppDomain aktivuje AppDomain.AssemblyResolve událost, že nemůže najít satelitní sestavení. Pokud se rozhodnete zpracovat událost, může obslužná rutina události načíst a vrátit odkaz na satelitní sestavení.
Pokud se najde satelitní sestavení, modul runtime ho vyhledá požadovaný prostředek. Pokud prostředek najde v sestavení, použije ho. Pokud prostředek nenajde, bude pokračovat ve vyhledávání.

Poznámka:

Pokud chcete najít prostředek v rámci satelitního sestavení, modul runtime vyhledá soubor prostředků požadovaný ResourceManager pro aktuální CultureInfo.Name. V souboru prostředků hledá požadovaný název prostředku. Pokud se některý z těchto prostředků nenajde, prostředek se považuje za nenalezeno.
Modul runtime dále prohledá sestavení nadřazené jazykové verze prostřednictvím mnoha potenciálních úrovní, pokaždé, když opakuje kroky 1 a 2.

Nadřazená jazyková verze je definována jako vhodná záložní jazyková verze. Zvažte rodiče jako náhradní kandidáty, protože poskytnutí jakéhokoli prostředku je vhodnější vyvolat výjimku. Tento proces také umožňuje opakovaně používat prostředky. Konkrétní prostředek byste měli zahrnout na nadřazené úrovni pouze v případě, že podřízená jazyková verze nepotřebuje lokalizovat požadovaný prostředek. Pokud například zadáte satelitní sestavení pro en (neutrální angličtinu), en-GB (angličtinu jako mluvený ve Spojeném království) a en-US (angličtinu, jak je uvedeno v USA), en satelit obsahuje společnou terminologii a en-GBen-US satelity poskytují přepsání pouze pro ty výrazy, které se liší.

Každá jazyková verze má pouze jeden nadřazený objekt, který je definován vlastností CultureInfo.Parent , ale nadřazený objekt může mít svůj vlastní nadřazený objekt. Hledání nadřazených jazykových verzí se zastaví, když vlastnost jazykové verze Parent vrátí CultureInfo.InvariantCulture. U náhradního prostředku není invariantní jazyková verze považována za nadřazenou jazykovou verzi ani jazykovou verzi, která může obsahovat prostředky.
Pokud byla původně zadaná jazyková verze a všechny nadřazené položky byly prohledávané a prostředek se stále nenajde, použije se prostředek pro výchozí (záložní) jazykovou verzi. Prostředky pro výchozí jazykovou verzi jsou obvykle zahrnuty do hlavního sestavení aplikace. Můžete však zadat hodnotu Satellite vlastnosti Location , která určuje, že konečným záložním umístěním pro prostředky je satelitní sestavení místo hlavního sestavení.

Poznámka:

Výchozí prostředek je jediný prostředek, který lze zkompilovat pomocí hlavního sestavení. Pokud nezadáte satelitní sestavení pomocí atributu NeutralResourcesLanguageAttribute , je to konečný záložní (konečný nadřazený). Proto doporučujeme, abyste do hlavního sestavení vždy zahrnuli výchozí sadu prostředků. To pomáhá zabránit vyvolání výjimek. Zahrnutím výchozího souboru prostředků poskytnete náhradní prostředky pro všechny prostředky a zajistíte, aby byl pro uživatele vždy k dispozici alespoň jeden prostředek, i když není kulturní.
A konečně, pokud modul runtime nenajde soubor prostředků pro výchozí (záložní) jazykovou verzi, MissingManifestResourceException vyvolá se chyba nebo MissingSatelliteAssemblyException výjimka, která značí, že se prostředek nepodařilo najít. Pokud je nalezen soubor prostředku, ale požadovaný prostředek není k dispozici požadavek vrátí null.

Ultimate náhradní do satelitní montáže

Volitelně můžete odebrat prostředky z hlavního sestavení a určit, že modul runtime by měl načíst konečné záložní prostředky ze satelitního sestavení, které odpovídá konkrétní jazykové verzi. Chcete-li řídit záložní proces, použijte NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) konstruktor a zadejte hodnotu parametru UltimateResourceFallbackLocation , který určuje, zda Resource Manager má extrahovat záložní prostředky z hlavního sestavení nebo ze satelitního sestavení.

Následující příklad rozhraní .NET Framework používá NeutralResourcesLanguageAttribute atribut k uložení záložních prostředků aplikace do satelitního sestavení pro francouzštinu (fr). Příklad obsahuje dva textové soubory prostředků, které definují jeden řetězcový prostředek s názvem Greeting. První resources.fr.txt obsahuje prostředek francouzského jazyka.

Greeting=Bon jour!

Druhý zdroj, prostředky, ru.txt, obsahuje ruský jazykový zdroj.

Greeting=Добрый день

Tyto dva soubory se kompilují do souborů .resources spuštěním generátoru souborů prostředků (resgen.exe) z příkazového řádku. Pro prostředek francouzského jazyka je příkaz:

resgen.exe resources.fr.txt

Pro prostředek ruského jazyka je příkaz:

resgen.exe resources.ru.txt

Soubory .resources jsou vloženy do dynamických knihoven propojení spuštěním Assembly Linker (al.exe) z příkazového řádku pro prostředek francouzského jazyka následujícím způsobem:

al /t:lib /embed:resources.fr.resources /culture:fr /out:fr\Example1.resources.dll

a pro prostředek ruského jazyka následujícím způsobem:

al /t:lib /embed:resources.ru.resources /culture:ru /out:ru\Example1.resources.dll

Zdrojový kód aplikace se nachází v souboru s názvem Example1.cs nebo Example1.vb. Obsahuje atribut, NeutralResourcesLanguageAttribute který označuje, že výchozí prostředek aplikace je v podadresáři fr. Vytvoří instanci Resource Manageru, načte hodnotu Greeting prostředku a zobrazí ji v konzole.

using System;
using System.Reflection;
using System.Resources;

[assembly:NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)]

public class Example
{
   public static void Main()
   {
      ResourceManager rm = new ResourceManager("resources",
                                               typeof(Example).Assembly);
      string greeting = rm.GetString("Greeting");
      Console.WriteLine(greeting);
   }
}

Imports System.Reflection
Imports System.Resources

<Assembly: NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)>
Module Example
    Public Sub Main()
        Dim rm As New ResourceManager("resources", GetType(Example).Assembly)
        Dim greeting As String = rm.GetString("Greeting")
        Console.WriteLine(greeting)
    End Sub
End Module

Zdrojový kód jazyka C# pak můžete zkompilovat z příkazového řádku následujícím způsobem:

csc Example1.cs

Příkaz kompilátoru jazyka Visual Basic je velmi podobný:

vbc Example1.vb

Vzhledem k tomu, že v hlavním sestavení nejsou vložené žádné prostředky, není nutné kompilovat pomocí /resource přepínače.

Když spustíte příklad ze systému, jehož jazyk je cokoli jiného než ruština, zobrazí následující výstup:

Bon jour!

Navrhovaná alternativní balení

Časová nebo rozpočtová omezení vám můžou bránit v vytváření sady prostředků pro každou subkultuře, kterou vaše aplikace podporuje. Místo toho můžete vytvořit jedno satelitní sestavení pro nadřazenou jazykovou verzi, kterou můžou používat všechny související subcultures. Můžete například zadat jedno anglické satelitní sestavení (en), které načte uživatelé, kteří požadují anglické prostředky specifické pro jednotlivé oblasti, a jedno německé satelitní sestavení (de) pro uživatele, kteří požadují německé prostředky specifické pro jednotlivé oblasti. Například žádosti o němčinu jako mluvené v Německu (de-DE), Rakousko (de-AT) a Švýcarsko (de-CH) by se vrátily do německého satelitního sestavení (de). Výchozí prostředky jsou posledním náhradním prostředkům, a proto by měly být prostředky, které budou vyžadovat většina uživatelů vaší aplikace, proto tyto prostředky pečlivě vyberte. Tento přístup nasazuje prostředky, které jsou méně specifické kulturně, ale může výrazně snížit náklady na lokalizaci vaší aplikace.