Resgen.exe (generátor zdrojových souborů)
Nástroj Resource File Generator (Resgen.exe) převádí textové soubory (.txt nebo .restext) a soubory ve formátu prostředků založeném na jazyce XML (.resx) na binární soubory modulu CLR (.resources), které mohou být vloženy do binárního spustitelného souboru modulu nebo satelitního sestavení. Další informace najdete v tématu Vytvoření souborů prostředků.
Resgen.exe je univerzální nástroj pro převod prostředků, který plní následující úlohy:
Převádí soubory .txt nebo .restext na soubory .resources nebo .resx. (Formát souborů .restext je stejný jako formát souborů .txt. Přípona .restext vám ale pomůže snadněji identifikovat textové soubory, které obsahují definice prostředků.)
Převádí soubory .resources na textové soubory nebo soubory .resx.
Převádí soubory .resx na textové soubory nebo soubory .resources.
Extrahuje řetězcové prostředky ze sestavení do souboru .resw, který je vhodný pro použití v aplikaci Windows 8.x Store.
Vytvoří třídu silného typu, která poskytuje přístup k jednotlivým pojmenovaným prostředkům ResourceManager a k instanci.
Pokud nástroj Resgen.exe z jakéhokoli důvodu selže, je návratová hodnota –1.
Pokud chcete získat nápovědu k Resgen.exe, můžete pomocí následujícího příkazu (bez zadaných možností) zobrazit syntaxi příkazu a možnosti pro Resgen.exe:
resgen
Můžete také použít /? přepínač:
resgen /?
Pokud použijete Resgen.exe ke generování binárních souborů .resources, můžete použít kompilátor jazyka pro vložení binárních souborů do spustitelných sestavení, nebo můžete použít Linker sestavení (Al.exe) ke kompilaci do satelitních sestavení.
Tento nástroj je automaticky nainstalován se sadou Visual Studio. Ke spuštění nástroje použijte Visual Studio Developer Command Prompt nebo Visual Studio Developer PowerShell.
V příkazovém řádku zadejte následující:
Syntaxe
resgen [-define:symbol1[,symbol2,...]] [/useSourcePath] filename.extension | /compile filename.extension... [outputFilename.extension] [/r:assembly] [/str:lang[,namespace[,class[,file]]] [/publicclass]]
resgen filename.extension [outputDirectory]
Parametry
| Parametr nebo přepínač | Description |
|---|---|
/define:symbol1[, symbol2,...] |
Počínaje rozhraním .NET Framework 4.5 podporuje podmíněnou kompilaci v textových (.txt nebo .restext) zdrojových souborech. Pokud symbol odpovídá symbolu, který je součástí vstupního textového souboru v konstruktoru #ifdef , je přidružený prostředek řetězce zahrnut do souboru .resources. Pokud vstupní textový soubor obsahuje #if ! příkaz se symbolem, který není definován přepínačem /define , je přidružený řetězcový prostředek zahrnut do souboru resources./define se ignoruje, pokud se používá s netextovými soubory. Rozlišují se malá a velká písmena.Další informace o této možnosti najdete v části Podmíněné kompilace prostředků dále v tomto tématu. |
useSourcePath |
Určuje, že k vyhodnocení relativních cest k souborům má být použit aktuální adresář vstupního souboru. |
/compile |
Umožňuje zadat několik textových souborů nebo souborů .resx pro převod na několik souborů .resources jednou hromadnou operací. Pokud tuto možnost nezadáte, lze zadat pouze jeden argument vstupního souboru. Výstupní soubory mají název filename.resources. Tuto možnost nelze použít s možností /str: .Další informace o této možnosti najdete v části Kompilace nebo převod více souborů dále v tomto tématu. |
/r: assembly |
Odkazuje na metadata z určeného sestavení. Používá se při převodu souborů .resx a umožňuje nástroji Resgen.exe serializovat a deserializovat prostředky objektů. Podobá se možnostem /reference: nebo /r: pro kompilátory jazyka C# a Visual Basic. |
filename.extension |
Určuje název vstupního souboru, který má být převeden. Pokud používáte první, delší syntaxi příkazového řádku před touto tabulkou, extension musí být jedna z následujících možností:.txt nebo .restext Textový soubor, který má být převeden na soubor .resources nebo .resx. Textové soubory mohou obsahovat pouze řetězcové prostředky. Informace o formátu souboru najdete v části "Prostředky v textových souborech" v tématu Vytvoření souborů prostředků. .resx Soubor prostředků založený na jazyce XML, který má být převeden na soubor .resources nebo textový soubor (.txt nebo .restext). .resources Binární soubor prostředků, který má být převeden na soubor .resx nebo textový soubor (.txt nebo .restext). Pokud používáte druhou kratší syntaxi příkazového řádku před touto tabulkou, extension musí být následující:.exe nebo .dll Sestavení rozhraní .NET Framework (spustitelné nebo knihovny), jehož řetězcové prostředky mají být extrahovány do souboru .resw pro účely vývoje aplikací pro Windows 8.x Store. |
outputFilename.extension |
Určuje název a typ souboru prostředků, který má být vytvořen. Při převodu ze souboru .txt, .restext nebo .resx na soubor .resources je tento argument nepovinný. Pokud nezadáte outputFilename, Resgen.exe ke vstupu filename připojí příponu .resources a zapíše soubor do adresáře, který obsahuje filename,extension.Argument outputFilename.extension je povinný při převodu ze souboru .resources. Při převodu souboru .resources na soubor prostředků založený na jazyce XML zadejte název souboru s příponou .resx. Při převodu souboru .resources na textový soubor zadejte název souboru s příponou .txt nebo restext. Soubor .resources by měl být na soubor .txt převeden pouze v případě, že soubor .resources obsahuje výhradně řetězcové hodnoty. |
outputDirectory |
Pro aplikace Windows 8.x Store určuje adresář, do kterého se zapíše soubor .resw, který obsahuje řetězcové prostředky.filename.extension outputDirectory musí již existovat. |
/str: language[,namespace[,classname[,filename]]] |
Vytvoří soubor třídy prostředků silného typu v programovacím jazyce zadaném v možnosti language . language může se skládat z jednoho z následujících literálů:- Pro C#: c#, csnebo csharp.– Pro Visual Basic: vb nebo visualbasic.- Pro VBScript: vbs nebo vbscript.- Pro C++: c++, mcnebo cpp.- Pro JavaScript: js, jscriptnebo javascript.Možnost namespace určuje výchozí obor názvů projektu, classname možnost určuje název vygenerované třídy a filename možnost určuje název souboru třídy.Možnost /str: umožňuje pouze jeden vstupní soubor, takže ji nelze použít s /compile možností .Pokud namespace je zadán, ale classname není, název třídy je odvozen z názvu výstupního souboru (například podtržítka jsou nahrazena tečkami). Prostředky se silnými typy možná důsledkem toho nebudou fungovat správně. Chcete-li se tomuto problému vyhnout, zadejte název třídy i název výstupního souboru.Další informace o této možnosti najdete v části Generování třídy prostředků silného typu dále v tomto tématu. |
/publicClass |
Vytvoří třídu prostředků se silnými typy jako veřejnou třídu. Ve výchozím nastavení je internal třída prostředků v jazyce C# a Friend v jazyce Visual Basic.Tato možnost je ignorována, pokud /str: není použita. |
Nástroj Resgen.exe a typy souborů prostředků
Aby nástroj Resgen.exe mohl úspěšně převádět prostředky, textové soubory a soubory .resx, musí dodržovat správný formát.
Textové soubory (.txt a .restext)
Textové soubory (.txt nebo .restext) mohou obsahovat výhradně řetězcové prostředky. Řetězcové prostředky jsou užitečné při psaní aplikace, která musí mít řetězce přeloženy do několika jazyků. Lze například snadno lokalizovat řetězce nabídky použitím příslušného řetězcového prostředku. Nástroj Resgen.exe čte textové soubory obsahující dvojice název/hodnota, kde název je řetězec popisující prostředek a hodnota je samotný řetězec prostředku.
Poznámka
Informace o formátu souborů .txt a .restext najdete v části "Prostředky v textových souborech" tématu Vytvoření souborů prostředků.
Neobsahuje-li textový soubor s prostředky pouze znaky z rozsahu základní latinky (do U+007F), musí být uložen s kódováním UTF-8 nebo Unicode (UTF-16). Při zpracovávání textového souboru uloženého s kódováním ANSI nástroj Resgen.exe odstraňuje rozšířené znaky ANSI.
Nástroj Resgen.exe kontroluje, zda textový soubor obsahuje duplicitní názvy prostředků. Obsahuje-li textový soubor duplicitní názvy prostředků, nástroj Resgen.exe vygeneruje upozornění a bude ignorovat druhou hodnotu.
Soubory .resx
Formát souboru prostředků .resx sestává ze záznamů jazyka XML. Uvnitř těchto záznamů jazyka XML lze zadávat řetězcové prostředky jako v textových souborech. Hlavní výhodou souborů .resx oproti textovým souborům je možnost zadávat nebo vkládat objekty. Při zobrazení souboru .resx lze vidět binární podobu vloženého objektu (například obrázku), pokud je tato binární informace součástí manifestu prostředku. Stejně jako textové soubory lze i soubory .resx otevřít v textovém editoru (například Poznámkový blok nebo Microsoft Word) a zapisovat, analyzovat či upravovat jejich obsah. To vyžaduje dobrou znalost značek XML a struktury souboru .resx. Další podrobnosti o formátu souboru .resx najdete v části "Prostředky v souborech .resx" v tématu Vytvoření souborů prostředků.
Chcete-li vytvořit soubor .resources, který obsahuje vložené neřetězecové objekty, musíte buď použít Resgen.exe k převodu souboru .resx obsahující objekty, nebo přidat prostředky objektu do souboru přímo z kódu voláním metod poskytovaných ResourceWriter třídou .
Obsahuje-li soubor .resx nebo .resources objekty a použijete-li nástroj Resgen.exe k jeho převodu na textový soubor, všechny řetězcové prostředky budou převedeny správně, ale datové typy neřetězcových objektů budou do souboru také zapsány jako řetězce. Během převodu dojde ke ztrátě vložených objektů a nástroj Resgen.exe oznámí, že při načítání prostředků došlo k chybě.
Převod mezi typy souborů prostředků
Při převádění mezi různými typy souborů prostředků nástroj Resgen.exe nemusí být schopen převod provést nebo může ztratit informace o určitých prostředcích v závislosti na zdrojovém a cílovém typu souboru. Následující tabulka obsahuje typy převodů, které jsou při převádění jednoho typu souboru prostředků na jiný úspěšné.
| Převod z | Na textový soubor | Na soubor .resx | Na soubor .resw | Na soubor .resources |
|---|---|---|---|---|
| Textový soubor (.txt nebo .restext) | -- | Žádné problémy | Nepodporováno | Žádné problémy |
| Soubor .resx | Obsahuje-li soubor neřetězcové prostředky (včetně odkazů na soubory), převod se nezdaří. | -- | Nepodporováno | Žádné problémy |
| Soubor .resources | Obsahuje-li soubor neřetězcové prostředky (včetně odkazů na soubory), převod se nezdaří. | Žádné problémy | Nepodporováno | -- |
| Sestavení .exe nebo .dll | Nepodporováno | Nepodporováno | Pouze řetězcové prostředky (včetně názvů cest) jsou rozpoznány jako prostředky | Nepodporováno |
Provádění konkrétních úloh nástroje Resgen.exe
Resgen.exe můžete použít různými způsoby: ke kompilaci textového souboru prostředků nebo souboru prostředků založeného na jazyce XML do binárního souboru, k převodu mezi formáty souborů prostředků a k vygenerování třídy, která zabalí ResourceManager funkce a poskytuje přístup k prostředkům. Tato část poskytuje podrobné informace o každém úkolu:
Kompilace prostředků do binárního souboru
Nejběžnější použití nástroje Resgen.exe je kompilování textového souboru prostředků (soubor .txt nebo .restext) nebo souboru prostředků založeného na jazyce XML (soubor .resx) do binárního souboru .resources. Výstupní soubor pak může být vložen do hlavního sestavení kompilátorem jazyka nebo do satelitního sestavení pomocí Assembly Linker (AL.exe).
Syntaxe pro kompilaci souboru prostředků je následující:
resgen inputFilename [outputFilename]
kde parametry jsou:
inputFilename Název souboru prostředku, včetně přípony, který se má zkompilovat. Nástroj Resgen.exe kompiluje pouze soubory s příponami .txt, .restext nebo .resx.
outputFilename Název výstupního souboru. Pokud vynecháte outputFilename, Resgen.exe vytvoří soubor .resources s názvem kořenového inputFilename souboru ve stejném adresáři jako inputFilename. Pokud outputFilename obsahuje cestu k adresáři, musí adresář existovat.
Souboru .resources je poskytován plně kvalifikovaný obor názvů jeho zadáním v názvu souboru a oddělením od názvu kořenového souboru tečkou. Pokud je MyCompany.Libraries.Strings.resourcesnapříklad outputFilename , obor názvů je MyCompany.Libraries.
Následující příklad přečte dvojice název/hodnota v souboru Resources.txt a zapíše binární soubor .resources pojmenovaný Resources.resources. Soubor dostane dle výchozího nastavení název shodný s názvem vstupního souboru, protože název výstupního souboru nebyl explicitně zadán.
resgen Resources.txt
Následující příkaz přečte dvojice název/hodnota v souboru Resources.restext a zapíše binární soubor .resources pojmenovaný StringResources.resources.
resgen Resources.restext StringResources.resources
Následující příkaz přečte vstupní soubor založený na jazyce XML pojmenovaný Resources.resx a zapíše binární soubor .resources pojmenovaný Resources.resources.
resgen Resources.resx Resources.resources
Převod mezi typy souborů prostředků
Kromě kompilování textových souborů prostředků nebo souborů prostředků založených na jazyce XML do binárních souborů .resources dokáže nástroj Resgen.exe také převést libovolný podporovaný typ souboru na libovolný jiný podporovaný typ. To znamená, že může provést následující převody:
Soubory .txt a .restext na soubory .resx.
Soubory .resx na soubory .txt a .restext.
Soubory .resources na soubory .txt a .restext.
Soubory .resources na soubory .resx.
Syntaxe je shodná se syntaxí uvedenou v předchozí části.
Kromě toho můžete použít Resgen.exe k převodu vložených prostředků v sestavení .NET Framework na tor souborů .resw Windows 8.x Store aplikací.
Následující příkaz přečte binární soubor prostředků Resources.resources a zapíše výstupní soubor založený na jazyce XML pojmenovaný Resources.resx.
resgen Resources.resources Resources.resx
Následující příkaz přečte vstupní textový soubor StringResources.txt a zapíše soubor prostředků založený na jazyce XML pojmenovaný LibraryResources.resx. Kromě řetězcových prostředků může být soubor .resx použit také pro uchování neřetězcových prostředků.
resgen StringResources.txt LibraryResources.resx
Následující dva příkazy přečtou vstupní soubor prostředků založený na jazyce XML pojmenovaný Resources.resx a zapíší textové soubory pojmenované Resources.txt a Resources.restext. Pokud soubor .resx obsahuje jakékoli vložené objekty, nebudou do textových souborů převedeny přesně.
resgen Resources.resx Resources.txt
resgen Resources.resx Resources.restext
Kompilace nebo převod více souborů
Přepínač můžete použít /compile k převodu seznamu souborů prostředků z jednoho formátu do jiného v rámci jedné operace. Syntaxe je:
resgen /compile filename.extension [filename.extension...]
Následující příkaz zkompiluje tři soubory, StringResources.txt, TableResources.resw a ImageResources.resw, do oddělených souborů .resources pojmenovaných StringResources.resources, TableResources.resources a ImageResources.resources.
resgen /compile StringResources.txt TableResources.resx ImageResources.resx
Exportování prostředků do souboru .resw
Pokud vyvíjíte aplikaci Windows 8.x Store, možná budete chtít použít prostředky z existující desktopové aplikace. Tyto dva druhy aplikací však používají různé formáty souborů. U aplikací klasické pracovní plochy jsou prostředky v textových souborech (.txt nebo .restext) nebo souborech .resx kompilovány do binárních souborů .resources. V aplikacích Windows 8.x Store se soubory .resw kompilují do souborů PRI (Binary Package Resource Index). Tuto mezeru můžete překlenout pomocí Resgen.exe extrahováním prostředků ze spustitelného nebo satelitního sestavení a jejich zápisem do jednoho nebo více souborů .resw, které lze použít při vývoji aplikace Windows 8.x Store.
Důležité
Visual Studio automaticky zpracovává všechny převody potřebné k začlenění prostředků v přenosné knihovně do aplikace Windows 8.x Store. Použití Resgen.exe přímo k převodu prostředků v sestavení do formátu souboru .resw je zajímavé jenom pro vývojáře, kteří chtějí vyvíjet aplikaci Windows 8.x Store mimo Visual Studio.
Syntaxe pro vygenerování souborů .resw ze sestavení je následující:
resgen filename.extension [outputDirectory]
kde parametry jsou:
filename.extension Název sestavení rozhraní .NET Framework (spustitelného souboru nebo .DLL). Neobsahuje-li soubor žádné prostředky, nástroj Resgen.exe nevytvoří žádné soubory.
outputDirectory Existující adresář, do kterého se mají zapisovat soubory .resw. Pokud outputDirectory je vynechán, soubory .resw se zapisují do aktuálního adresáře. Nástroj Resgen.exe vytváří jeden soubor .resw pro každý soubor .resources v sestavení. Kořenový název souboru .resw je stejný jako kořenový název souboru .resources.
Následující příkaz vytvoří pro každý soubor .resources vložený do aplikace MyApp.exe soubor .resw v adresáři Win8Resources:
resgen MyApp.exe Win8Resources
Podmíněná kompilace prostředků
Počínaje rozhraním .NET Framework 4.5 podporuje Resgen.exe podmíněnou kompilaci prostředků řetězců v textových souborech (.txt a .restext). To umožňuje použití jediného textového souboru prostředků v několika konfiguracích sestavení.
V souboru .txt nebo .restext použijete #ifdef...#endif konstruktor, který zahrne prostředek do binárního souboru .resources, pokud je definován symbol, a použijete #if !konstruktor ... #endif k zahrnutí prostředku, pokud symbol není definován. V době kompilace pak definujete symboly pomocí /define: možnosti následované seznamem symbolů oddělených čárkami. Při porovnání se rozlišují velká a malá písmena. velká písmena symbolů definovaných nástrojem /define musí odpovídat písmenům symbolů v textových souborech, které se mají zkompilovat.
Například následující soubor s názvem UIResources.rext obsahuje prostředek řetězce s názvem AppTitle , který může mít jednu ze tří hodnot v závislosti na tom, zda jsou definovány symboly s názvem PRODUCTION, CONSULTnebo RETAIL .
#ifdef PRODUCTION
AppTitle=My Software Company Project Manager
#endif
#ifdef CONSULT
AppTitle=My Consulting Company Project Manager
#endif
#ifdef RETAIL
AppTitle=My Retail Store Project Manager
#endif
FileMenuName=File
Soubor může být poté zkompilován do binárního souboru .resources následujícím příkazem:
resgen /define:CONSULT UIResources.restext
To vytvoří soubor .resources obsahující dva řetězcové prostředky. Hodnota AppTitle zdroje je "Projektový manažer mé konzultační společnosti".
Generování třídy prostředků se silnými typy
Nástroj Resgen.exe podporuje prostředky se silnými typy, což zapouzdřuje přístup k prostředkům vytvořením tříd obsahujících sadu statických vlastností určených pouze pro čtení. To poskytuje alternativu k přímému ResourceManager volání metod třídy pro načtení prostředků. Podporu prostředků silného /str typu můžete povolit pomocí možnosti v Resgen.exe, která zabalí funkce StronglyTypedResourceBuilder třídy. Když zadáte /str možnost, výstupem Resgen.exe je třída, která obsahuje vlastnosti silného typu, které odpovídají prostředkům, na které se odkazuje ve vstupním parametru. Tato třída poskytuje k prostředkům dostupným ve zpracovaném souboru přístup se silnými typy určený pouze pro čtení.
Syntaxe pro vytvoření prostředku se silnými typy je následující:
resgen inputFilename [outputFilename] /str:language[,namespace,[classname[,filename]]] [/publicClass]
Parametry a přepínače jsou následující:
inputFilename Název souboru, včetně přípony, souboru prostředků, pro který se má vygenerovat třída prostředků silného typu. Souborem může být textový soubor, binární soubor .resources nebo soubor založený na jazyce XML. Může mít příponu .txt, .restext, .resw nebo .resources.
outputFilename Název výstupního souboru. Pokud outputFilename obsahuje cestu k adresáři, musí adresář existovat. Pokud vynecháte outputFilename, Resgen.exe vytvoří soubor .resources s názvem kořenového inputFilename souboru ve stejném adresáři jako inputFilename.
outputFilename může být textový soubor založený na jazyce XML nebo binární soubor .resources. Pokud se přípona outputFilename souboru liší od přípony inputFilenamesouboru Resgen.exe provede převod souboru.
Pokud inputFilename je soubor .resources, Resgen.exe zkopíruje soubor .resources, pokud outputFilename je také soubor .resources. Pokud outputFilename je vynechán, Resgen.exe přepíše inputFilename identickým souborem .resources.
Jazyk Jazyk, ve kterém se má generovat zdrojový kód pro třídu prostředků silného typu. Možné hodnoty jsou cs, C#a csharp pro kód vb jazyka C# a visualbasic pro kód vbs jazyka Visual Basic a vbscript pro kód jazyka VBScript a c++, mca cpp pro kód jazyka C++.
Obor názvů Obor názvů, který obsahuje třídu prostředků silného typu. Soubor .resources a třída prostředků by měly mít stejný obor názvů. Informace o určení oboru názvů v souboru najdete v outputFilenametématu Kompilace prostředků do binárního souboru. Pokud je obor názvů vynechán, třída prostředků není obsažena v oboru názvů.
Classname Název třídy prostředků silného typu. Tento parametr by měl odpovídat názvu kořenového souboru .resources. Pokud například nástroj Resgen.exe vygeneruje soubor .resources pojmenovaný MyCompany.Libraries.Strings.resources, název třídy prostředků silného typu je Strings. Pokud je název_třídy vynechán, vygenerovaná třída je odvozena z kořenového názvu objektu outputFilename. Pokud outputFilename je vynechána, vygenerovaná třída je odvozena z kořenového názvu .inputFilename
classname nesmí obsahovat neplatné znaky, například vložené mezery. Pokud classname obsahuje vložené mezery nebo pokud je název třídy generován ve výchozím nastavení z inputFilename a inputFilename obsahuje vložené mezery, Resgen.exe nahradí všechny neplatné znaky podtržítkem (_).
Název_souboru Název souboru třídy.
/publicclass Nastaví třídu prostředků silného typu na veřejnou místo internal (v jazyce C#) nebo Friend (v jazyce Visual Basic). To umožňuje přístup k prostředkům z míst mimo sestavení, v němž jsou vloženy.
Důležité
Při vytváření třídy prostředku se silnými typy se musí název souboru .resources shodovat s oborem názvů a názvem třídy generovaného kódu. Nástroj Resgen.exe však umožňuje zadat možnosti, které vytvoří soubor .resources nekompatibilního názvu. Chcete-li toto chování obejít, přejmenujte po vygenerování výstupní soubor.
Třída prostředků se silnými typy má následující členy:
Konstruktor bez parametrů, který lze použít k vytvoření instance třídy prostředků silného typu.
Vlastnost
static(C#) neboShared(Visual Basic) a jen proResourceManagerčtení, která vrací ResourceManager instanci, která spravuje prostředek silného typu.Statická
Culturevlastnost, která umožňuje nastavit jazykovou verzi používanou pro načítání prostředků. Ve výchozím nastavení jenulljeho hodnota , což znamená, že se používá aktuální jazyková verze uživatelského rozhraní.Jedna
staticvlastnost (C#) neboShared(Visual Basic) a jen pro čtení pro každý prostředek v souboru .resources. Název vlastnosti je názvem prostředku.
Například následující příkaz zkompiluje soubor prostředků s názvem StringResources.txt do StringResources.resources a vygeneruje třídu s názvem StringResources v souboru zdrojového kódu jazyka Visual Basic s názvem StringResources.vb, který lze použít pro přístup k Resource Manager.
resgen StringResources.txt /str:vb,,StringResources