Partilhar via

Resgen.exe (Gerador de arquivos de recursos)

  • Artigo

O Resource File Generator (Resgen.exe) converte arquivos de texto (.txt ou .restext) e arquivos de formato de recurso baseado em XML (.resx) em arquivos binários (.resources) de Common Language Runtime que podem ser incorporados em um executável binário de tempo de execução ou assembly satélite. Para obter mais informações, consulte Criar arquivos de recursos.

Resgen.exe é um utilitário de conversão de recursos de uso geral que executa as seguintes tarefas:

  • Converte arquivos .txt ou .restext em arquivos .resources ou .resx. (O formato dos arquivos .restext é idêntico ao formato dos arquivos .txt. No entanto, a extensão .restext ajuda você a identificar arquivos de texto que contêm definições de recursos mais facilmente.)

  • Converte arquivos .resources em arquivos de texto ou .resx.

  • Converte arquivos .resx em arquivos de texto ou .resources.

  • Extrai os recursos de cadeia de caracteres de um assembly em um arquivo .resw adequado para uso em um aplicativo da Windows Store 8.x.

  • Cria uma classe fortemente tipada que fornece acesso a recursos nomeados individuais e à ResourceManager instância.

Se Resgen.exe falhar por qualquer motivo, o valor de retorno será –1.

Para obter ajuda com Resgen.exe, você pode usar o seguinte comando, sem opções especificadas, para exibir a sintaxe do comando e as opções para Resgen.exe:

resgen

Você também pode usar o /? switch:

resgen /?

Se você usar Resgen.exe para gerar arquivos .resources binários, poderá usar um compilador de linguagem para incorporar os arquivos binários em assemblies executáveis ou poderá usar o Assembly Linker (Al.exe) para compilá-los em assemblies satélite.

Esta ferramenta é instalada automaticamente com o Visual Studio. Para executar a ferramenta, use o Visual Studio Developer Command Prompt ou o Visual Studio Developer PowerShell.

Na linha de comandos, escreva o seguinte:

Sintaxe

resgen  [-define:symbol1[,symbol2,...]] [/useSourcePath] filename.extension  | /compile filename.extension... [outputFilename.extension] [/r:assembly] [/str:lang[,namespace[,class[,file]]] [/publicclass]]

resgen filename.extension [outputDirectory]

Parâmetros

Parâmetro ou interruptor Description
/define:symbol1[, symbol2,...] A partir do .NET Framework 4.5, oferece suporte à compilação condicional em arquivos de recursos baseados em texto (.txt ou .restext). Se symbol corresponder a um símbolo incluído no arquivo de texto de entrada dentro de uma #ifdef construção, o recurso de cadeia de caracteres associado será incluído no arquivo .resources. Se o arquivo de texto de entrada incluir uma #if ! instrução com um símbolo que não é definido pela /define opção, o recurso de cadeia de caracteres associado será incluído no arquivo de recursos.

/define é ignorado se for usado com arquivos que não sejam de texto. Os símbolos diferenciam maiúsculas de minúsculas.

Para obter mais informações sobre essa opção, consulte Compilando recursos condicionalmente mais adiante neste tópico.
useSourcePath Especifica que o diretório atual do arquivo de entrada deve ser usado para resolver caminhos de arquivo relativos.
/compile Permite especificar vários arquivos .resx ou de texto para converter em vários arquivos .resources em uma única operação em massa. Se você não especificar essa opção, poderá especificar apenas um argumento de arquivo de entrada. Os arquivos de saída são nomeados filename.resources.

Esta opção não pode ser usada com a /str: opção.

Para obter mais informações sobre essa opção, consulte Compilando ou convertendo vários arquivos posteriormente neste tópico.
/r: assembly Faz referência a metadados do assembly especificado. Ele é usado ao converter arquivos .resx e permite que Resgen.exe serialize ou desserialize recursos de objeto. É semelhante às /reference: opções ou /r: para os compiladores C# e Visual Basic.
filename.extension Especifica o nome do arquivo de entrada a ser convertido. Se você estiver usando a primeira sintaxe de linha de comando mais longa apresentada antes desta tabela, extension deve ser uma das seguintes:

.txt ou .restext
Um arquivo de texto para converter em um arquivo .resources ou .resx. Os arquivos de texto podem conter apenas recursos de cadeia de caracteres. Para obter informações sobre o formato de arquivo, consulte a seção "Recursos em arquivos de texto" de Criar arquivos de recurso.

.resx
Um arquivo de recurso baseado em XML para converter em um arquivo .resources ou um arquivo de texto (.txt ou .restext).

no local.
Um arquivo de recurso binário para converter em um arquivo .resx ou um arquivo de texto (.txt ou .restext).

Se você estiver usando a segunda sintaxe de linha de comando mais curta apresentada antes desta tabela, extension deve ser a seguinte:

.exe ou .dll
Um assembly do .NET Framework (executável ou biblioteca) cujos recursos de cadeia de caracteres devem ser extraídos para um arquivo .resw para uso no desenvolvimento de aplicativos da Windows Store 8.x.
outputFilename.extension Especifica o nome e o tipo do arquivo de recurso a ser criado.

Esse argumento é opcional ao converter de um arquivo .txt, .restext ou .resx para um arquivo .resources. Se você não especificar outputFilename, Resgen.exe acrescentará uma extensão .resources à entrada filename e gravará o arquivo no diretório que contém filename,extension.

O outputFilename.extension argumento é obrigatório ao converter de um arquivo .resources. Especifique um nome de arquivo com a extensão .resx ao converter um arquivo .resources em um arquivo de recurso baseado em XML. Especifique um nome de arquivo com a extensão .txt ou .restext ao converter um arquivo .resources em um arquivo de texto. Você deve converter um arquivo .resources em um arquivo .txt somente quando o arquivo .resources contiver apenas valores de cadeia de caracteres.
outputDirectory Para aplicativos da Windows Store 8.x, especifica o diretório no qual um arquivo .resw que contém os recursos de cadeia de caracteres em filename.extension será gravado. outputDirectory já deve existir.
/str: language[,namespace[,classname[,filename]]] Cria um arquivo de classe de recurso fortemente tipado na linguagem de programação especificada na language opção. language pode consistir em um dos seguintes literais:

- Para C#: c#, cs, ou csharp.
- Para Visual Basic: vb ou visualbasic.
- Para VBScript: vbs ou vbscript.
- Para C++: c++, mc, ou cpp.
- Para JavaScript: js, jscript, ou javascript.

A namespace opção especifica o namespace padrão do projeto, a classname opção especifica o nome da classe gerada e a filename opção especifica o nome do arquivo de classe.

A /str: opção permite apenas um arquivo de entrada, portanto, não pode ser usado com a /compile opção.

Se namespace for especificado, mas classname não for, o nome da classe será derivado do nome do arquivo de saída (por exemplo, sublinhados são substituídos por pontos). Como resultado, os recursos fortemente tipados podem não funcionar corretamente. Para evitar isso, especifique o nome da classe e o nome do arquivo de saída.

Para obter mais informações sobre essa opção, consulte Gerando uma classe de recurso fortemente tipada posteriormente neste tópico.
/publicClass Cria uma classe de recurso fortemente tipada como uma classe pública. Por padrão, a classe de recurso está internal em C# e Friend no Visual Basic.

Esta opção será ignorada se não /str: for usada.

Tipos de arquivo Resgen.exe e de recursos

Para que Resgen.exe converta recursos com sucesso, os arquivos de texto e .resx devem seguir o formato correto.

Arquivos de texto (.txt e .restext)

Os arquivos de texto (.txt ou .restext) podem conter apenas recursos de cadeia de caracteres. Os recursos de cadeia de caracteres são úteis se você estiver escrevendo um aplicativo que deve ter cadeias de caracteres traduzidas em vários idiomas. Por exemplo, você pode regionalizar facilmente cadeias de caracteres de menu usando o recurso de cadeia de caracteres apropriado. Resgen.exe lê arquivos de texto que contêm pares nome/valor, onde o nome é uma cadeia de caracteres que descreve o recurso e o valor é a própria cadeia de caracteres de recurso.

Nota

Para obter informações sobre o formato de arquivos .txt e .restext, consulte a seção "Recursos em arquivos de texto" de Criar arquivos de recurso.

Um arquivo de texto que contém recursos deve ser salvo com codificação UTF-8 ou Unicode (UTF-16), a menos que contenha apenas caracteres no intervalo latino básico (até U+007F). Resgen.exe remove caracteres ANSI estendidos quando processa um arquivo de texto que é salvo usando a codificação ANSI.

Resgen.exe verifica o arquivo de texto em busca de nomes de recursos duplicados. Se o arquivo de texto contiver nomes de recursos duplicados, Resgen.exe emitirá um aviso e ignorará o segundo valor.

Arquivos .resx

O formato de arquivo de recurso .resx consiste em entradas XML. Você pode especificar recursos de cadeia de caracteres dentro dessas entradas XML, como faria em arquivos de texto. Uma vantagem principal dos arquivos .resx em relação aos arquivos de texto é que você também pode especificar ou incorporar objetos. Quando visualiza um ficheiro .resx, pode ver a forma binária de um objeto incorporado (por exemplo, uma imagem) quando esta informação binária faz parte do manifesto do recurso. Tal como acontece com os ficheiros de texto, pode abrir um ficheiro .resx com um editor de texto (como o Bloco de Notas ou o Microsoft Word) e escrever, analisar e manipular o seu conteúdo. Observe que isso requer um bom conhecimento de marcas XML e da estrutura do arquivo .resx. Para obter mais detalhes sobre o formato de arquivo .resx, consulte a seção "Recursos em arquivos .resx" de Criar arquivos de recurso.

Para criar um arquivo .resources que contenha objetos não string incorporados, você deve usar Resgen.exe para converter um arquivo .resx contendo objetos ou adicionar os recursos de objeto ao seu arquivo diretamente do código chamando os métodos fornecidos pela ResourceWriter classe.

Se o arquivo .resx ou .resources contiver objetos e você usar Resgen.exe para convertê-lo em um arquivo de texto, todos os recursos de cadeia de caracteres serão convertidos corretamente, mas os tipos de dados dos objetos sem cadeia de caracteres também serão gravados no arquivo como cadeias de caracteres. Você perderá os objetos incorporados na conversão e Resgen.exe relatará que ocorreu um erro na recuperação dos recursos.

Convertendo entre tipos de arquivo de recursos

Quando você converte entre diferentes tipos de arquivo de recurso, Resgen.exe pode não ser capaz de executar a conversão ou pode perder informações sobre recursos específicos, dependendo dos tipos de arquivo de origem e destino. A tabela a seguir especifica os tipos de conversões que são bem-sucedidas ao converter de um tipo de arquivo de recurso para outro.

Converter de Para o arquivo de texto Para o arquivo .resx Para o arquivo .resw Para o arquivo .resources
Arquivo de texto (.txt ou .restext) -- Não existem problemas Não suportado Não existem problemas
Arquivo .resx A conversão falhará se o arquivo contiver recursos que não sejam de cadeia de caracteres (incluindo links de arquivos) -- Não suportado* Não existem problemas
Arquivo .resources A conversão falhará se o arquivo contiver recursos que não sejam de cadeia de caracteres (incluindo links de arquivos) Não existem problemas Não suportado --
.exe ou .dll montagem Não suportado Não suportado Somente recursos de cadeia de caracteres (incluindo nomes de caminho) são reconhecidos como recursos Não suportado

*Nas aplicações da Loja Windows 8.x, utiliza ficheiros .resw para criar recursos. Apesar da diferença de extensão de arquivo, o formato de arquivo .resw é idêntico ao formato de arquivo .resx, exceto que os arquivos .resw podem conter apenas cadeias de caracteres e caminhos de arquivo. Você pode converter arquivos .resx que contêm apenas cadeias de caracteres e caminhos de arquivo em arquivos .resw simplesmente alterando a extensão do arquivo.

Execução de tarefas Resgen.exe específicas

Você pode usar Resgen.exe de diversas maneiras: para compilar um arquivo de recurso baseado em texto ou XML em um arquivo binário, para converter entre formatos de arquivo de recurso e para gerar uma classe que encapsula a ResourceManager funcionalidade e fornece acesso a recursos. Esta seção fornece informações detalhadas sobre cada tarefa:

Compilando recursos em um arquivo binário

O uso mais comum do Resgen.exe é compilar um arquivo de recurso baseado em texto (um arquivo .txt ou .restext) ou um arquivo de recurso baseado em XML (um arquivo .resx) em um arquivo binário .resources. O arquivo de saída pode então ser incorporado em um assembly principal por um compilador de linguagem ou em um assembly satélite pelo Assembly Linker (AL.exe).

A sintaxe para compilar um arquivo de recurso é:

resgen inputFilename [outputFilename]

onde os parâmetros são:

inputFilename O nome do arquivo, incluindo a extensão, do arquivo de recurso a ser compilado. Resgen.exe compila apenas arquivos com extensões de .txt, .restext ou .resx.

outputFilename O nome do arquivo de saída. Se você omitir outputFilenameo , Resgen.exe criará um arquivo .resources com o nome do arquivo raiz de inputFilename no mesmo diretório que inputFilename. Se outputFilename incluir um caminho de diretório, o diretório deve existir.

Você fornece um namespace totalmente qualificado para o arquivo .resources especificando-o no nome do arquivo e separando-o do nome do arquivo raiz por um ponto. Por exemplo, se outputFilename for MyCompany.Libraries.Strings.resources, o namespace será MyCompany.Libraries.

O comando a seguir lê os pares nome/valor no Resources.txt e grava um arquivo .resources binário chamado Resources.resources. Como o nome do arquivo de saída não é especificado explicitamente, ele recebe o mesmo nome que o arquivo de entrada por padrão.

resgen Resources.txt

O comando a seguir lê os pares nome/valor em Resources.restext e grava um arquivo de recursos binários chamado StringResources.resources.

resgen Resources.restext StringResources.resources

O comando a seguir lê um arquivo de entrada baseado em XML chamado Resources.resx e grava um arquivo binário .resources chamado Resources.resources.

resgen Resources.resx Resources.resources

Convertendo entre tipos de arquivo de recurso

Além de compilar arquivos de recursos baseados em texto ou XML em arquivos binários .resources, Resgen.exe pode converter qualquer tipo de arquivo suportado em qualquer outro tipo de arquivo suportado. Isso significa que ele pode executar as seguintes conversões:

  • .txt e arquivos .restext para arquivos .resx.

  • .resx para arquivos .txt e .restext.

  • .resources para arquivos .txt e .restext.

  • .resources para arquivos .resx.

A sintaxe é a mesma mostrada na seção anterior.

Além disso, você pode usar Resgen.exe para converter recursos incorporados em um assembly do .NET Framework em um arquivo .resw para aplicativos da Windows Store 8.x.

O comando a seguir lê um arquivo de recursos binários Resources.resources e grava um arquivo de saída baseado em XML chamado Resources.resx.

resgen Resources.resources Resources.resx

O comando a seguir lê um arquivo de recursos baseado em texto chamado StringResources.txt e grava um arquivo de recursos baseado em XML chamado LibraryResources.resx. Além de conter recursos de cadeia de caracteres, o arquivo .resx também pode ser usado para armazenar recursos que não sejam de cadeia de caracteres.

resgen StringResources.txt LibraryResources.resx

Os dois comandos a seguir leem um arquivo de recursos baseado em XML chamado Resources.resx e gravam arquivos de texto chamados Resources.txt e Resources.restext. Observe que, se o arquivo .resx contiver objetos incorporados, eles não serão convertidos com precisão nos arquivos de texto.

resgen Resources.resx Resources.txt
resgen Resources.resx Resources.restext

Compilando ou convertendo vários arquivos

Você pode usar a /compile opção para converter uma lista de arquivos de recursos de um formato para outro em uma única operação. A sintaxe é:

resgen /compile filename.extension [filename.extension...]

O comando a seguir compila três arquivos, StringResources.txt, TableResources.resw e ImageResources.resw, em arquivos .resources separados chamados StringResources.resources, TableResources.resources e ImageResources.resources.

resgen /compile StringResources.txt TableResources.resx ImageResources.resx

Exportando recursos para um arquivo .resw

Se estiver a desenvolver uma aplicação da Loja Windows 8.x, poderá querer utilizar recursos de uma aplicação de ambiente de trabalho existente. No entanto, os dois tipos de aplicativos suportam formatos de arquivo diferentes. Em aplicativos de área de trabalho, os recursos em arquivos de texto (.txt ou .restext) ou .resx são compilados em arquivos binários .resources. Em aplicativos da Windows Store 8.x, os arquivos .resw são compilados em arquivos binários de índice de recursos de pacote (PRI). Você pode usar Resgen.exe para preencher essa lacuna extraindo recursos de um executável ou de um assembly satélite e gravando-os em um ou mais arquivos .resw que podem ser usados ao desenvolver um aplicativo da Windows Store 8.x.

Importante

O Visual Studio lida automaticamente com todas as conversões necessárias para incorporar os recursos em uma biblioteca portátil em um aplicativo da Windows Store 8.x. Usar Resgen.exe diretamente para converter os recursos em um assembly para o formato de arquivo .resw é de interesse apenas para desenvolvedores que desejam desenvolver um aplicativo da Windows Store 8.x fora do Visual Studio.

A sintaxe para gerar arquivos .resw a partir de um assembly é:

resgen filename.extension  [outputDirectory]

onde os parâmetros são:

filename.extension O nome de um assembly do .NET Framework (um executável ou .DLL). Se o arquivo não contiver recursos, Resgen.exe não criará nenhum arquivo.

outputDirectory O diretório existente no qual gravar os arquivos .resw. Se outputDirectory for omitido, os arquivos .resw serão gravados no diretório atual. Resgen.exe cria um arquivo .resw para cada arquivo .resources no assembly. O nome do arquivo raiz do arquivo .resw é o mesmo que o nome raiz do arquivo .resources.

O comando a seguir cria um arquivo .resw no diretório Win8Resources para cada arquivo .resources incorporado no MyApp.exe:

resgen MyApp.exe Win8Resources

Compilando recursos condicionalmente

A partir do .NET Framework 4.5, Resgen.exe oferece suporte à compilação condicional de recursos de cadeia de caracteres em arquivos de texto (.txt e .restext). Isso permite que você use um único arquivo de recurso baseado em texto em várias configurações de compilação.

Em um arquivo .txt ou .restext, você usa o #ifdef...#endif construct para incluir um recurso no arquivo binário .resources se um símbolo for definido, e você usa a #if !construção ... #endif para incluir um recurso se um símbolo não estiver definido. Em tempo de compilação, você define símbolos usando a opção seguida por uma lista delimitada por vírgulas /define: de símbolos. A comparação diferencia maiúsculas de minúsculas. O caso dos símbolos definidos por /define deve corresponder ao caso dos símbolos nos arquivos de texto a serem compilados.

Por exemplo, o seguinte arquivo chamado UIResources.text inclui um recurso de cadeia de caracteres chamado AppTitle que pode ter um dos três valores, dependendo se os símbolos nomeados PRODUCTION, CONSULTou RETAIL estão definidos.

#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

O arquivo pode então ser compilado em um arquivo .resources binário com o seguinte comando:

resgen /define:CONSULT UIResources.restext

Isso produz um arquivo .resources que contém dois recursos de cadeia de caracteres. O valor do AppTitle recurso é "My Consulting Company Project Manager".

Gerando uma classe de recurso fortemente tipada

Resgen.exe oferece suporte a recursos fortemente tipados, que encapsula o acesso a recursos criando classes que contêm um conjunto de propriedades estáticas somente leitura. Isso fornece uma alternativa para chamar os métodos da ResourceManager classe diretamente para recuperar recursos. Você pode habilitar o suporte a recursos fortemente tipados usando a /str opção em Resgen.exe, que encapsula a StronglyTypedResourceBuilder funcionalidade da classe. Quando você especifica a /str opção, a saída de Resgen.exe é uma classe que contém propriedades fortemente tipadas que correspondem aos recursos referenciados no parâmetro de entrada. Essa classe fornece acesso somente leitura fortemente tipado para os recursos que estão disponíveis no arquivo processado.

A sintaxe para criar um recurso fortemente tipado é:

resgen inputFilename [outputFilename] /str:language[,namespace,[classname[,filename]]] [/publicClass]

Os parâmetros e interruptores são:

inputFilename O nome do arquivo, incluindo a extensão, do arquivo de recurso para o qual gerar uma classe de recurso fortemente tipada. O arquivo pode ser baseado em texto, XML ou binário .resources; ele pode ter uma extensão de .txt, .restext, .resw ou .resources.

outputFilename O nome do arquivo de saída. Se outputFilename incluir um caminho de diretório, o diretório deve existir. Se você omitir outputFilenameo , Resgen.exe criará um arquivo .resources com o nome do arquivo raiz de inputFilename no mesmo diretório que inputFilename.

outputFilename pode ser um arquivo .resources baseado em texto, XML ou binário. Se a extensão do arquivo do outputFilename é diferente da extensão do arquivo do inputFilename, Resgen.exe executa a conversão do arquivo.

Se inputFilename for um arquivo .resources, Resgen.exe copiará o arquivo .resources se outputFilename também for um arquivo .resources. Se outputFilename for omitido, Resgen.exe substitui inputFilename por um arquivo .resources idêntico.

language A linguagem na qual gerar código-fonte para a classe de recurso fortemente tipada. Os valores possíveis são cs, C#e csharp para o código C#, vb e visualbasic para o código Visual Basic, vbs e vbscript para o código VBScript, e c++, mce cpp para o código C++.

namespace O namespace que contém a classe de recurso fortemente tipada. O arquivo .resources e a classe resource devem ter o mesmo namespace. Para obter informações sobre como especificar o namespace no outputFilename, consulte Compilando recursos em um arquivo binário. Se o namespace for omitido, a classe de recurso não estará contida em um namespace.

classname O nome da classe de recurso fortemente tipada. Isso deve corresponder ao nome raiz do arquivo .resources. Por exemplo, se Resgen.exe gerar um arquivo .resources chamado MyCompany.Libraries.Strings.resources, o nome da classe de recurso fortemente tipada será Strings. Se classname for omitido, a classe gerada será derivada do nome raiz de outputFilename. Se outputFilename for omitida, a classe gerada será derivada do nome raiz de inputFilename.

ClassName não pode conter caracteres inválidos, como espaços incorporados. Se classname contiver espaços incorporados, ou se classname for gerado por padrão de inputFilename, e inputFilename contiver espaços incorporados, Resgen.exe substituirá todos os caracteres inválidos por um sublinhado (_).

filename O nome do arquivo de classe.

/publicclass Torna pública a classe de recurso fortemente tipada em vez de internal (em C#) ou Friend (em Visual Basic). Isso permite que os recursos sejam acessados de fora do assembly no qual estão inseridos.

Importante

Quando você cria uma classe de recurso fortemente tipada, o nome do arquivo .resources deve corresponder ao namespace e ao nome da classe do código gerado. No entanto, Resgen.exe permite especificar opções que produzem um arquivo .resources com um nome incompatível. Para contornar esse comportamento, renomeie o arquivo de saída depois que ele foi gerado.

A classe de recurso fortemente tipada tem os seguintes membros:

  • Um construtor sem parâmetros, que pode ser usado para instanciar a classe de recurso fortemente tipada.

  • Uma static propriedade (C#) ou Shared (Visual Basic) e somente ResourceManager leitura, que retorna a ResourceManager instância que gerencia o recurso fortemente tipado.

  • Uma propriedade estática Culture , que permite definir a cultura usada para recuperação de recursos. Por padrão, seu valor é null, o que significa que a cultura atual da interface do usuário é usada.

  • Uma static (C#) ou Shared (Visual Basic) e propriedade somente leitura para cada recurso no arquivo .resources. O nome da propriedade é o nome do recurso.-

Por exemplo, o comando a seguir compila um arquivo de recurso chamado StringResources.txt em StringResources.resources e gera uma classe nomeada StringResources em um arquivo de código-fonte do Visual Basic chamado StringResources.vb que pode ser usado para acessar o Gerenciador de Recursos.

resgen StringResources.txt /str:vb,,StringResources

Consulte também