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 .txt souborů. Rozšíření .restext však pomáhá 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 pro Windows 8.x Store.
Vytvoří třídu silného typu, která poskytuje přístup k jednotlivým pojmenovaným prostředkům a instanci ResourceManager .
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 k zobrazení syntaxe příkazu a možností pro Resgen.exe použít následující příkaz bez zadaných možností:
resgen
Přepínač můžete použít /? také:
resgen /?
Pokud používáte Resgen.exe ke generování binárních souborů .resources, můžete použít kompilátor jazyka k 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.
Na 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č | Popis |
|---|---|
/define:symbol1[, symbol2,...] |
Počínaje rozhraním .NET Framework 4.5 podporuje podmíněnou kompilaci v textových souborech prostředků (.txt nebo .restext). Pokud symbol odpovídá symbolu obsaženému ve vstupním textovém souboru v rámci 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 /define přepínačem, je přidružený prostředek řetězce zahrnut do souboru prostředků./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 naleznete v tématu 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 /str: touto možností.Další informace o této možnosti naleznete v tématu 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 kompilátorů /r: jazyka /reference: 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 těchto věcí:.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 Zdroje v textových souborech v části 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ý soubor nebo knihovna), jehož řetězcové prostředky se mají extrahovat do souboru .resw pro použití při vývoji 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 připojí k vstupu filename 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 |
U aplikací pro Windows 8.x Store určuje adresář, do kterého se zapíše soubor .resw obsahující ř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 language v možnosti. 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.Tato /str: možnost 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 naleznete v tématu 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 se ignoruje, pokud /str: se tato možnost nepoužívá. |
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 naleznete v části Zdroje v textových souborech v části 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 části Vytvoření souborů prostředků.
Chcete-li vytvořit soubor .resources, který obsahuje vložené netřetězecí 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 |
*V aplikacích pro Windows 8.x Store použijete soubory .resw k vytváření prostředků. Navzdory rozdílu přípony souboru je formát souboru .resw stejný jako formát souboru .resx s tím rozdílem, že soubory .resw mohou obsahovat pouze řetězce a cesty k souborům. Soubory .resx, které obsahují pouze řetězce a cesty k souborům .resw můžete převést jednoduše změnou přípony souboru.
Provádění konkrétních úloh nástroje Resgen.exe
Můžete použít Resgen.exe různými způsoby: ke kompilaci textového souboru 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, včetně přípony, souboru prostředku, 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 outputFilename je MyCompany.Libraries.Strings.resourcesnapříklad , 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 pomocí Resgen.exe převést vložené prostředky v sestavení .NET Framework na soubor .resw pro aplikace pro Windows 8.x Store.
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ů
Pomocí přepínače můžete /compile převést seznam 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 pro Windows 8.x Store, můžete 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 pro Windows 8.x Store se soubory .resw kompilují do souborů indexu prostředků binárního balíčku (PRI). Tuto mezeru můžete překlenout pomocí Resgen.exe extrahováním prostředků ze spustitelného souboru nebo satelitního sestavení a jejich zápisem do jednoho nebo více souborů .resw, které lze použít při vývoji aplikace pro Windows 8.x Store.
Důležité
Visual Studio automaticky zpracovává všechny převody potřebné k začlenění prostředků do přenosné knihovny do aplikace pro 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é pouze pro vývojáře, kteří chtějí vyvíjet aplikaci pro 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ý soubor nebo .DLL). Neobsahuje-li soubor žádné prostředky, nástroj Resgen.exe nevytvoří žádné soubory.
outputDirectory Existující adresář, do kterého chcete 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 Resgen.exe podporuje podmíněnou kompilaci řetězcových prostředků 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é čárkami odděleným seznamem symbolů. V porovnání se rozlišují malá a velká písmena. Velikost písmen symbolů definovaných /define v textových souborech se musí shodovat s písmeny v textových souborech, které se mají zkompilovat.
Například následující soubor s názvem UIResources.text obsahuje řetězcový prostředek s názvem AppTitle , který může mít jednu ze tří hodnot v závislosti na tom, zda jsou symboly s názvem PRODUCTION, CONSULTnebo RETAIL jsou definovány.
#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 "My Consulting Company Project Manager".
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 volání metod ResourceManager třídy přímo k načtení prostředků. Podporu prostředků silného StronglyTypedResourceBuilder typu můžete povolit pomocí /str možnosti v Resgen.exe, která zabalí funkce třídy. Když zadáte /str možnost, výstup Resgen.exe je třída, která obsahuje vlastnosti silného typu, které odpovídají prostředkům odkazovaným 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ředku, 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í .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 tento parametr vynecháte, Resgen.exe přepsat inputFilename identickým souborem .resources.
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++mc, a cpp pro kód jazyka C++.
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 části outputFilenameCompiling Resources into a Binary File. 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 název třídy vynecháte, vygenerovaná třída je odvozena od kořenového názvu .outputFilename Pokud outputFilename je vynechán, vygenerovaná třída je odvozena od kořenového názvu .inputFilename
classname nemůže obsahovat neplatné znaky, jako jsou vložené mezery. Pokud název třídy obsahuje vložené mezery nebo pokud název třídy je ve výchozím nastavení generován z inputFilename a inputFilename obsahuje vložené mezery, Resgen.exe nahradí všechny neplatné znaky podtržítkem (_).
název souboru třídy.
/publicclass Zpřístupňuje třídu prostředků silného typu 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.
A
static(C#) neboShared(Visual Basic) a vlastnost jen proResourceManagerčtení, která vrací ResourceManager instanci, která spravuje prostředek silného typu.Statická
Culturevlastnost, která umožňuje nastavit jazykovou verzi použitou 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
static(C#) neboShared(Visual Basic) a vlastnost jen pro čtení pro každý prostředek v souboru .resources. Název vlastnosti je názvem prostředku.
Následující příkaz například zkompiluje soubor prostředků s názvem StringResources.txt do StringResources.resources a vygeneruje třídu pojmenovanou StringResources v souboru zdrojového kódu jazyka Visual Basic s názvem StringResources.vb, který lze použít pro přístup k Resource Manageru.
resgen StringResources.txt /str:vb,,StringResources
