Criar arquivos de recursos para aplicativos .NET
Você pode incluir recursos, como cadeias de caracteres, imagens ou dados de objeto, em arquivos de recursos para torná-los facilmente disponíveis para seu aplicativo. O .NET Framework oferece cinco maneiras de criar arquivos de recursos:
Crie um arquivo de texto que contenha recursos de cadeia de caracteres. Você pode usar o Resource File Generator (resgen.exe) para converter o arquivo de texto em um arquivo de recurso binário (.resources). Em seguida, você pode incorporar o arquivo de recurso binário em um executável de aplicativo ou em uma biblioteca de aplicativos usando um compilador de linguagem ou pode incorporá-lo em um assembly satélite usando o Assembly Linker (Al.exe). Para obter mais informações, consulte a seção Recursos em arquivos de texto.
Crie um arquivo de recurso XML (.resx) que contenha dados de cadeia de caracteres, imagem ou objeto. Você pode usar o Resource File Generator (resgen.exe) para converter o arquivo .resx em um arquivo de recurso binário (.resources). Em seguida, você pode incorporar o arquivo de recurso binário em um executável de aplicativo ou em uma biblioteca de aplicativos usando um compilador de linguagem ou pode incorporá-lo em um assembly satélite usando o Assembly Linker (Al.exe). Para obter mais informações, consulte a seção Recursos em arquivos .resx.
Crie um arquivo de recurso XML (.resx) programaticamente usando tipos no System.Resources namespace. Você pode criar um arquivo .resx, enumerar seus recursos e recuperar recursos específicos pelo nome. Para obter mais informações, consulte Trabalhando com arquivos .resx programaticamente.
Crie um arquivo de recurso binário (.resources) programaticamente. Em seguida, você pode incorporar o arquivo em um executável de aplicativo ou em uma biblioteca de aplicativos usando um compilador de linguagem ou pode incorporá-lo em um assembly satélite usando o Assembly Linker (Al.exe). Para obter mais informações, consulte a seção Recursos em arquivos .resources.
Use o Visual Studio para criar um arquivo de recurso e incluí-lo em seu projeto. Visual Studio fornece um editor de recursos que permite adicionar, excluir e modificar recursos. Em tempo de compilação, o arquivo de recurso é convertido automaticamente em um arquivo .resources binário e incorporado em um assembly de aplicativo ou assembly satélite. Para obter mais informações, consulte a seção Arquivos de recursos no Visual Studio .
Recursos em ficheiros de texto
Você pode usar arquivos de texto (.txt ou .restext) para armazenar somente recursos de cadeia de caracteres. Para recursos que não sejam de cadeia de caracteres, use arquivos .resx ou crie-os programaticamente. Os arquivos de texto que contêm recursos de cadeia de caracteres têm o seguinte formato:
# This is an optional comment.
name = value
; This is another optional comment.
name = value
; The following supports conditional compilation if X is defined.
#ifdef X
name1=value1
name2=value2
#endif
# The following supports conditional compilation if Y is undefined.
#if !Y
name1=value1
name2=value2
#endif
O formato de arquivo de recurso dos arquivos .txt e .restext é idêntico. A extensão do arquivo .restext serve apenas para tornar os arquivos de texto imediatamente identificáveis como arquivos de recursos baseados em texto.
Os recursos de cadeia de caracteres aparecem como pares nome/valor , onde name é uma cadeia de caracteres que identifica o recurso e value é a cadeia de caracteres de recurso que é retornada quando você passa nome para um método de recuperação de recurso, como ResourceManager.GetString. nome e valor devem ser separados por um sinal de igual (=). Por exemplo:
FileMenuName=File
EditMenuName=Edit
ViewMenuName=View
HelpMenuName=Help
Atenção
Não use arquivos de recursos para armazenar senhas, informações confidenciais de segurança ou dados privados.
Cadeias de caracteres vazias (ou seja, um recurso cujo valor é String.Empty) são permitidas em arquivos de texto. Por exemplo:
EmptyString=
Começando com o .NET Framework 4.5 e em todas as versões do .NET Core, os arquivos de texto suportam compilação condicional com as construções símbolo#ifdef... #endif e #if !símbolo... #endif Em seguida, você pode usar a opção com o /define Resource File Generator (resgen.exe) para definir símbolos. Cada recurso requer seu próprio #ifdefsímbolo... #endif ou#if ! símbolo... #endif construir. Se você usar uma #ifdef instrução e o símbolo for definido, o recurso associado será incluído no arquivo .resources, caso contrário, ele não será incluído. Se você usar uma #if ! instrução e o símbolo não estiver definido, o recurso associado será incluído no arquivo .resources, caso contrário, ele não será incluído.
Os comentários são opcionais em arquivos de texto e são precedidos por um ponto-e-vírgula (;) ou por um sinal de libra (#) no início de uma linha. As linhas que contêm comentários podem ser colocadas em qualquer lugar do arquivo. Os comentários não são incluídos em um arquivo .resources compilado que é criado usando o Resource File Generator (resgen.exe).
Todas as linhas em branco nos arquivos de texto são consideradas espaço em branco e são ignoradas.
O exemplo a seguir define dois recursos de cadeia de caracteres chamados OKButton e CancelButton.
#Define resources for buttons in the user interface.
OKButton=OK
CancelButton=Cancel
Se o arquivo de texto contiver ocorrências duplicadas de nome, o Resource File Generator (resgen.exe) exibirá um aviso e ignorará o segundo nome.
value não pode conter novos caracteres de linha, mas você pode usar caracteres de escape no estilo de linguagem C, como \n para representar uma nova linha e \t para representar uma guia. Você também pode incluir um caractere de barra invertida se ele for escapado (por exemplo, "\\"). Além disso, uma string vazia é permitida.
Salve recursos no formato de arquivo de texto usando a codificação UTF-8 ou UTF-16 em ordem de bytes little-endian ou big-endian. No entanto, o Resource File Generator (resgen.exe), que converte um arquivo .txt em um arquivo .resources, trata os arquivos como UTF-8 por padrão. Se desejar que Resgen.exe reconheça um arquivo que foi codificado usando UTF-16, você deve incluir uma marca de ordem de bytes Unicode (U + FEFF) no início do arquivo.
Para incorporar um arquivo de recurso em formato de texto em um assembly .NET, você deve converter o arquivo em um arquivo de recurso binário (.resources) usando o Resource File Generator (resgen.exe). Em seguida, você pode incorporar o arquivo .resources em um assembly .NET usando um compilador de linguagem ou incorporá-lo em um assembly satélite usando Assembly Linker (Al.exe).
O exemplo a seguir usa um arquivo de recurso em formato de texto chamado GreetingResources.txt para um aplicativo de console "Hello World" simples. O arquivo de texto define duas cadeias de caracteres prompt e greeting, que solicitam que o usuário insira seu nome e exiba uma saudação.
# GreetingResources.txt
# A resource file in text format for a "Hello World" application.
#
# Initial prompt to the user.
prompt=Enter your name:
# Format string to display the result.
greeting=Hello, {0}!
O arquivo de texto é convertido em um arquivo .resources usando o seguinte comando:
resgen GreetingResources.txt
O exemplo a seguir mostra o código-fonte de um aplicativo de console que usa o arquivo .resources para exibir mensagens para o usuário.
using System;
using System.Reflection;
using System.Resources;
public class Example
{
public static void Main()
{
ResourceManager rm = new ResourceManager("GreetingResources",
typeof(Example).Assembly);
Console.Write(rm.GetString("prompt"));
string name = Console.ReadLine();
Console.WriteLine(rm.GetString("greeting"), name);
}
}
// The example displays output like the following:
// Enter your name: Wilberforce
// Hello, Wilberforce!
Imports System.Reflection
Imports System.Resources
Module Example
Public Sub Main()
Dim rm As New ResourceManager("GreetingResources",
GetType(Example).Assembly())
Console.Write(rm.GetString("prompt"))
Dim name As String = Console.ReadLine()
Console.WriteLine(rm.GetString("greeting"), name)
End Sub
End Module
' The example displays output like the following:
' Enter your name: Wilberforce
' Hello, Wilberforce!
Se você estiver usando o Visual Basic e o arquivo de código-fonte for chamado Greeting.vb, o comando a seguir criará um arquivo executável que inclui o arquivo .resources incorporado:
vbc greeting.vb -resource:GreetingResources.resources
Se você estiver usando C# e o arquivo de código-fonte for chamado Greeting.cs, o comando a seguir criará um arquivo executável que inclui o arquivo .resources incorporado:
csc greeting.cs -resource:GreetingResources.resources
Recursos em arquivos .resx
Ao contrário dos arquivos de texto, que só podem armazenar recursos de cadeia de caracteres, os arquivos de recursos XML (.resx) podem armazenar cadeias de caracteres, dados binários, como imagens, ícones e clipes de áudio e objetos programáticos. Um arquivo .resx contém um cabeçalho padrão, que descreve o formato das entradas de recurso e especifica as informações de controle de versão para o XML usado para analisar os dados. Os dados do arquivo de recurso seguem o cabeçalho XML. Cada item de dados consiste em um par nome/valor contido em uma data tag. Seu name atributo define o nome do recurso e a tag aninhada value contém o valor do recurso. Para dados de cadeia de caracteres, a value tag contém a cadeia de caracteres.
Por exemplo, a tag a seguir data define um recurso de cadeia de caracteres chamado prompt cujo valor é "Digite seu nome:".
<data name="prompt" xml:space="preserve">
<value>Enter your name:</value>
</data>
Atenção
Não use arquivos de recursos para armazenar senhas, informações confidenciais de segurança ou dados privados.
Para objetos de recurso, a marca de dados inclui um type atributo que indica o tipo de dados do recurso. Para objetos que consistem em dados binários, a data tag também inclui um mimetype atributo, que indica o base64 tipo de dados binários.
Nota
Todos os arquivos .resx usam um formatador de serialização binário para gerar e analisar os dados binários para um tipo especificado. Como resultado, um arquivo .resx pode se tornar inválido se o formato de serialização binário para um objeto for alterado de forma incompatível.
O exemplo a seguir mostra uma parte de um arquivo .resx que inclui um Int32 recurso e uma imagem bitmap.
<data name="i1" type="System.Int32, mscorlib">
<value>20</value>
</data>
<data name="flag" type="System.Drawing.Bitmap, System.Drawing,
Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
mimetype="application/x-microsoft.net.object.bytearray.base64">
<value>
AAEAAAD/////AQAAAAAAAAAMAgAAADtTeX…
</value>
</data>
Importante
Como os arquivos .resx devem consistir em XML bem formado em um formato predefinido, não recomendamos trabalhar com arquivos .resx manualmente, especialmente quando os arquivos .resx contêm recursos diferentes de cadeias de caracteres. Em vez disso, o Visual Studio fornece uma interface transparente para criar e manipular arquivos .resx. Para obter mais informações, consulte a seção Arquivos de recursos no Visual Studio . Você também pode criar e manipular arquivos .resx programaticamente. Para obter mais informações, consulte Trabalhar com arquivos .resx programaticamente.
Recursos em arquivos .resources
Você pode usar a System.Resources.ResourceWriter classe para criar programaticamente um arquivo de recurso binário (.resources) diretamente do código. Você também pode usar o Resource File Generator (resgen.exe) para criar um arquivo .resources a partir de um arquivo de texto ou de um arquivo .resx. O arquivo .resources pode conter dados binários (matrizes de bytes) e dados de objeto, além de dados de cadeia de caracteres. A criação programática de um arquivo .resources requer as seguintes etapas:
Crie um ResourceWriter objeto com um nome de arquivo exclusivo. Você pode fazer isso especificando um nome de arquivo ou um fluxo de arquivo para um ResourceWriter construtor de classe.
Chame uma das sobrecargas do ResourceWriter.AddResource método para cada recurso nomeado para adicionar ao arquivo. O recurso pode ser uma cadeia de caracteres, um objeto ou uma coleção de dados binários (uma matriz de bytes).
Chame o ResourceWriter.Close método para gravar os recursos no arquivo e fechar o ResourceWriter objeto.
Atenção
Não use arquivos de recursos para armazenar senhas, informações confidenciais de segurança ou dados privados.
O exemplo a seguir cria programaticamente um arquivo .resources chamado CarResources.resources que armazena seis cadeias de caracteres, um ícone e dois objetos definidos pelo aplicativo (dois Automobile objetos). A Automobile classe, que é definida e instanciada no exemplo, é marcada com o atributo, o SerializableAttribute que permite que ela seja persistida pelo formatador de serialização binária.
using System;
using System.Drawing;
using System.Resources;
[Serializable()] public class Automobile
{
private string carMake;
private string carModel;
private int carYear;
private int carDoors;
private int carCylinders;
public Automobile(string make, string model, int year) :
this(make, model, year, 0, 0)
{ }
public Automobile(string make, string model, int year,
int doors, int cylinders)
{
this.carMake = make;
this.carModel = model;
this.carYear = year;
this.carDoors = doors;
this.carCylinders = cylinders;
}
public string Make {
get { return this.carMake; }
}
public string Model {
get { return this.carModel; }
}
public int Year {
get { return this.carYear; }
}
public int Doors {
get {
return this.carDoors; }
}
public int Cylinders {
get {
return this.carCylinders; }
}
}
public class Example
{
public static void Main()
{
// Instantiate an Automobile object.
Automobile car1 = new Automobile("Ford", "Model N", 1906, 0, 4);
Automobile car2 = new Automobile("Ford", "Model T", 1909, 2, 4);
// Define a resource file named CarResources.resx.
using (ResourceWriter rw = new ResourceWriter(@".\CarResources.resources"))
{
rw.AddResource("Title", "Classic American Cars");
rw.AddResource("HeaderString1", "Make");
rw.AddResource("HeaderString2", "Model");
rw.AddResource("HeaderString3", "Year");
rw.AddResource("HeaderString4", "Doors");
rw.AddResource("HeaderString5", "Cylinders");
rw.AddResource("Information", SystemIcons.Information);
rw.AddResource("EarlyAuto1", car1);
rw.AddResource("EarlyAuto2", car2);
}
}
}
Imports System.Drawing
Imports System.Resources
<Serializable()> Public Class Automobile
Private carMake As String
Private carModel As String
Private carYear As Integer
Private carDoors AS Integer
Private carCylinders As Integer
Public Sub New(make As String, model As String, year As Integer)
Me.New(make, model, year, 0, 0)
End Sub
Public Sub New(make As String, model As String, year As Integer,
doors As Integer, cylinders As Integer)
Me.carMake = make
Me.carModel = model
Me.carYear = year
Me.carDoors = doors
Me.carCylinders = cylinders
End Sub
Public ReadOnly Property Make As String
Get
Return Me.carMake
End Get
End Property
Public ReadOnly Property Model As String
Get
Return Me.carModel
End Get
End Property
Public ReadOnly Property Year As Integer
Get
Return Me.carYear
End Get
End Property
Public ReadOnly Property Doors As Integer
Get
Return Me.carDoors
End Get
End Property
Public ReadOnly Property Cylinders As Integer
Get
Return Me.carCylinders
End Get
End Property
End Class
Module Example
Public Sub Main()
' Instantiate an Automobile object.
Dim car1 As New Automobile("Ford", "Model N", 1906, 0, 4)
Dim car2 As New Automobile("Ford", "Model T", 1909, 2, 4)
' Define a resource file named CarResources.resx.
Using rw As New ResourceWriter(".\CarResources.resources")
rw.AddResource("Title", "Classic American Cars")
rw.AddResource("HeaderString1", "Make")
rw.AddResource("HeaderString2", "Model")
rw.AddResource("HeaderString3", "Year")
rw.AddResource("HeaderString4", "Doors")
rw.AddResource("HeaderString5", "Cylinders")
rw.AddResource("Information", SystemIcons.Information)
rw.AddResource("EarlyAuto1", car1)
rw.AddResource("EarlyAuto2", car2)
End Using
End Sub
End Module
Depois de criar o arquivo .resources, você pode incorporá-lo em um executável ou biblioteca de tempo de execução incluindo a opção do /resource compilador de linguagem ou incorporá-lo em um assembly satélite usando o Assembly Linker (Al.exe).
Arquivos de recursos no Visual Studio
Quando você adiciona um arquivo de recurso ao seu projeto do Visual Studio , o Visual Studio cria um arquivo .resx no diretório do projeto. O Visual Studio fornece editores de recursos que permitem adicionar cadeias de caracteres, imagens e objetos binários. Como os editores são projetados para lidar apenas com dados estáticos, eles não podem ser usados para armazenar objetos programáticos; Você deve gravar dados de objeto em um arquivo .resx ou em um arquivo .resources programaticamente. Para obter mais informações, consulte Trabalhar com arquivos .resx programaticamente e a seção Recursos em arquivos .resources.
Se você estiver adicionando recursos localizados, dê a eles o mesmo nome de arquivo raiz que o arquivo de recurso principal. Você também deve designar sua cultura no nome do arquivo. Por exemplo, se você adicionar um arquivo de recurso chamado Resources.resx, também poderá criar arquivos de recursos chamados Resources.en-US.resx e Resources.fr-FR.resx para armazenar recursos localizados para as culturas inglês (Estados Unidos) e francês (França), respectivamente. Você também deve designar a cultura padrão do seu aplicativo. Esta é a cultura cujos recursos são usados se não forem encontrados recursos localizados para uma determinada cultura.
Para especificar a cultura padrão, no Gerenciador de Soluções no Visual Studio:
- Abra as propriedades do projeto, clique com o botão direito do mouse no projeto e selecione Propriedades (ou Alt + Enter quando o projeto for selecionado).
- Selecione a guia Pacote .
- Na área Geral, selecione o idioma/cultura apropriado no controle de idioma neutro da Assembleia.
- Guardar as suas alterações.
Em tempo de compilação, o Visual Studio primeiro converte os arquivos .resx em um projeto em arquivos de recurso binário (.resources) e os armazena em um subdiretório do diretório obj do projeto. Visual Studio incorpora quaisquer arquivos de recurso que não contêm recursos localizados no assembly principal que é gerado pelo projeto. Se quaisquer arquivos de recursos contiverem recursos localizados, o Visual Studio os incorporará em assemblies satélite separados para cada cultura localizada. Em seguida, armazena cada montagem satélite em um diretório cujo nome corresponde à cultura localizada. Por exemplo, os recursos localizados em inglês (Estados Unidos) são armazenados em um assembly satélite no subdiretório en-US.
