System.Resources.ResourceManager classe

A classe ResourceManager recupera recursos de um arquivo .resources binário incorporado em um assembly ou de um arquivo .resources autônomo. Se um aplicativo tiver sido localizado e recursos localizados tiverem sido implantados em assemblies satélite, ele procurará recursos específicos da cultura, fornecerá fallback de recursos quando um recurso localizado não existir e dará suporte à serialização de recursos.

Aplicações de ambiente de trabalho

Para aplicativos de área de trabalho, a classe ResourceManager recupera recursos de arquivos de recursos binários (.resources). Normalmente, um compilador de linguagem ou o Assembly Linker (AL.exe) incorpora esses arquivos de recursos em um assembly. Você também pode usar um objeto ResourceManager para recuperar recursos diretamente de um arquivo .resources que não está incorporado em um assembly, chamando o método CreateFileBasedResourceManager.

Em uma aplicação baseada em recursos, um ficheiro .resources contém os recursos da cultura padrão, os quais são usados se nenhum recurso específico da cultura puder ser encontrado. Por exemplo, se a cultura padrão de um aplicativo for inglês (en), os recursos do idioma inglês serão usados sempre que recursos localizados não puderem ser encontrados para uma cultura específica, como inglês (Estados Unidos) (en-US) ou francês (França) (fr-FR). Normalmente, os recursos para a cultura predefinida são incorporados no assembly da aplicação principal e os recursos para outras culturas localizadas são incorporados em assemblies satélite. Os conjuntos de satélites contêm apenas recursos. Eles têm o mesmo nome de ficheiro raiz que a assemblagem principal e uma extensão de .resources.dll. Para aplicativos cujos assemblies não estão registrados no cache global de assemblies, os assemblies satélite são armazenados em um subdiretório de aplicativo cujo nome corresponde à cultura do assembly.

Criar recursos

Ao desenvolver um aplicativo baseado em recursos, você armazena informações de recursos em arquivos de texto (arquivos que têm uma extensão .txt ou .restext) ou arquivos XML (arquivos que têm uma extensão .resx). Em seguida, compile os arquivos de texto ou XML com o Resource File Generator (Resgen.exe) para criar um arquivo binário .resources. Em seguida, pode incorporar o arquivo .resources resultante num executável ou biblioteca usando uma opção de compilador, como /resources para os compiladores C# e Visual Basic, ou pode incorporá-lo numa assemblagem satélite usando o Assembly Linker (AI.exe). Se você incluir um arquivo .resx em seu projeto do Visual Studio, o Visual Studio manipulará a compilação e incorporação de recursos padrão e localizados automaticamente como parte do processo de compilação.

Idealmente, você deve criar recursos para cada idioma compatível com seu aplicativo ou, pelo menos, para um subconjunto significativo de cada idioma. Os nomes de ficheiro .resources binários seguem a convenção de nomenclatura nome base.cultureName.resources, onde basename é o nome da aplicação ou o nome de uma classe, dependendo do nível de detalhe desejado. A propriedade CultureInfo.Name é usada para determinar nomeDaCultura. Um recurso para a cultura padrão do aplicativo deve ser nomeado nome base.resources.

Por exemplo, suponha que um assembly tenha vários recursos em um arquivo de recurso que tenha o nome base MyResources. Esses arquivos de recursos devem ter nomes como MyResources.ja-JP.resources para a cultura japonesa, MyResources.de.resources para a cultura alemã, MyResources.zh-CHS.resources para a cultura chinesa simplificada e MyResources.fr-BE.resources para a cultura francesa (Bélgica). O arquivo de recurso padrão deve ser chamado MyResources.resources. Os arquivos de recursos específicos da cultura são comumente empacotados em assemblies satélite para cada cultura. O arquivo de recurso padrão deve ser incorporado no assembly principal do aplicativo.

Observe que Assembly Linker permite que os recursos sejam marcados como privados, mas deve sempre marcá-los como públicos para que possam ser acedidos por outros conjuntos. (Como um assembly satélite não contém código, os recursos marcados como privados não estão disponíveis para seu aplicativo por meio de qualquer mecanismo.)

Para obter mais informações sobre como criar, empacotar e implantar recursos, consulte os artigos Criando arquivos de recursos, Criando assemblies satélitee empacotando e implantando recursos.

Instanciar um objeto ResourceManager

Você instancia um objeto da classe ResourceManager que recupera recursos de um arquivo .resources incorporado chamando uma das suas sobrecargas do construtor da classe. Isso combina fortemente um objeto ResourceManager com um arquivo .resources específico e com quaisquer arquivos .resources localizados associados em assemblies satélite.

Os dois construtores mais comumente chamados são:

• ResourceManager(String, Assembly) pesquisa recursos com base em duas informações fornecidas: o nome base do arquivo .resources e o assembly no qual o arquivo .resources padrão reside. O nome base inclui o namespace e o nome raiz do arquivo .resources, sem sua cultura ou extensão. Observe que os arquivos .resources que são compilados a partir da linha de comando normalmente não incluem um nome de namespace, enquanto os arquivos .resources que são criados no ambiente do Visual Studio o fazem. Por exemplo, se um arquivo de recurso é chamado MyCompany.StringResources.resources e o construtor ResourceManager é chamado a partir de um método estático chamado Example.Main, o código a seguir instancia um objeto ResourceManager que pode recuperar recursos do arquivo .resources:

  ResourceManager rm = new ResourceManager("MyCompany.StringResources",
                                           typeof(Example).Assembly);
  

  Dim rm As New ResourceManager("MyCompany.StringResources",
                              GetType(Example2).Assembly)
  

• ResourceManager(Type) procura recursos em conjuntos satélite com base em informações de um objeto tipo. O nome totalmente qualificado do tipo corresponde ao nome base do ficheiro .resources sem a sua extensão. Em aplicativos de área de trabalho que são criados usando o Visual Studio Resource Designer, Visual Studio cria uma classe wrapper cujo nome totalmente qualificado é o mesmo que o nome raiz do arquivo .resources. Por exemplo, se um arquivo de recurso é chamado MyCompany.StringResources.resources e há uma classe wrapper chamada MyCompany.StringResources, o código a seguir instancia um objeto ResourceManager que pode recuperar recursos do arquivo .resources:

  ResourceManager rm = new ResourceManager(typeof(MyCompany.StringResources));
  

  Dim rm As New ResourceManager(GetType(MyCompany.StringResources))
  

Se os recursos apropriados não puderem ser encontrados, a chamada do construtor criará um objeto ResourceManager válido. No entanto, a tentativa de recuperar um recurso lança uma exceção MissingManifestResourceException. Para obter informações sobre como lidar com a exceção, consulte a seção Handle MissingManifestResourceException e MissingSatelliteAssemblyException mais adiante neste artigo.

O exemplo a seguir mostra como instanciar um objeto ResourceManager. Ele contém o código-fonte de um executável chamado ShowTime.exe. Ele também inclui o seguinte arquivo de texto chamado Strings.txt que contém um único recurso de cadeia de caracteres, TimeHeader:

TimeHeader=The current time is

Você pode usar um arquivo em lotes para gerar o arquivo de recurso e incorporá-lo ao executável. Aqui está o arquivo em lotes para gerar um executável usando o compilador C#:

resgen strings.txt
csc ShowTime.cs /resource:strings.resources

Para o compilador do Visual Basic, você pode usar o seguinte arquivo em lotes:

resgen strings.txt
vbc ShowTime.vb /resource:strings.resources

using System;
using System.Resources;

public class ShowTimeEx
{
    public static void Main()
    {
        ResourceManager rm = new ResourceManager("Strings",
                                 typeof(Example).Assembly);
        string timeString = rm.GetString("TimeHeader");
        Console.WriteLine($"{timeString} {DateTime.Now:T}");
    }
}
// The example displays output like the following:
//        The current time is 2:03:14 PM

Imports System.Resources

Module Example6
    Public Sub Main()
        Dim rm As New ResourceManager("Strings", GetType(Example6).Assembly)
        Dim timeString As String = rm.GetString("TimeHeader")
        Console.WriteLine("{0} {1:T}", timeString, Date.Now)
    End Sub
End Module
' The example displays output similar to the following:
'       The current time is 2:03:14 PM

ResourceManager e recursos específicos de cultura

Um aplicativo localizado requer recursos a serem implantados, conforme discutido no artigo Empacotando e implantando recursos. Se os assemblies estiverem configurados corretamente, o gerenciador de recursos determinará quais recursos recuperar com base na propriedade Thread.CurrentUICulture do thread atual. (Essa propriedade também retorna a cultura da interface do usuário do thread atual.) Por exemplo, se um aplicativo for compilado com recursos padrão em inglês no assembly principal e com recursos nos idiomas francês e russo em dois assemblies satélite e a propriedade Thread.CurrentUICulture estiver definida como fr-FR, o gerenciador de recursos recuperará os recursos em francês.

Você pode definir a propriedade CurrentUICulture explícita ou implicitamente. A maneira como você o define determina como o objeto ResourceManager recupera recursos com base na cultura:

• Se você definir explicitamente a propriedade Thread.CurrentUICulture para uma cultura específica, o gerenciador de recursos sempre recuperará os recursos para essa cultura, independentemente do idioma do navegador ou do sistema operacional do usuário. Considere um aplicativo compilado com recursos padrão em inglês e três assemblies satélite que contêm recursos para inglês (Estados Unidos), francês (França) e russo (Rússia). Se a propriedade CurrentUICulture estiver definida como fr-FR, o objeto ResourceManager sempre recuperará os recursos franceses (França), mesmo que o idioma do sistema operacional do usuário não seja francês. Certifique-se de que este é o comportamento desejado antes de definir a propriedade explicitamente.

  Em aplicativos ASP.NET, você deve definir a propriedade Thread.CurrentUICulture explicitamente, porque é improvável que a configuração no servidor corresponda às solicitações de entrada do cliente. Um aplicativo ASP.NET pode definir a propriedade Thread.CurrentUICulture explicitamente para o idioma de aceitação do navegador do usuário.

  A definição explícita da propriedade Thread.CurrentUICulture define a cultura atual da interface de utilizador para este tópico. Isso não afeta a cultura atual da interface do usuário de nenhum outro thread em um aplicativo.

• Você pode definir a cultura da interface do usuário de todos os threads em um domínio de aplicativo atribuindo um objeto CultureInfo que representa essa cultura à propriedade CultureInfo.DefaultThreadCurrentUICulture estática.

• Se você não definir explicitamente a cultura da interface do usuário atual e não definir uma cultura padrão para o domínio do aplicativo atual, a propriedade CultureInfo.CurrentUICulture será definida implicitamente pela função GetUserDefaultUILanguage do Windows. Esta função é fornecida pela Interface do Usuário Multilíngüe (MUI), que permite ao usuário definir o idioma padrão. Se o idioma da interface do usuário não for definido pelo usuário, ele assumirá como padrão o idioma instalado no sistema, que é o idioma dos recursos do sistema operacional.

O exemplo simples "Hello world" a seguir define a cultura atual da interface do usuário explicitamente. Contém recursos para três culturas: inglês (Estados Unidos) ou en-US, francês (França) ou fr-FRe russo (Rússia) ou ru-RU. Os recursos en-US estão contidos em um arquivo de texto chamado Greetings.txt:

HelloString=Hello world!

Os recursos fr-FR estão contidos em um arquivo de texto chamado Greetings.fr-FR.txt:

HelloString=Salut tout le monde!

Os recursos ru-RU estão contidos em um arquivo de texto chamado Greetings.ru-RU.txt:

HelloString=Всем привет!

Aqui está o código-fonte para o exemplo (Example.vb para a versão do Visual Basic ou Example.cs para a versão C#):

using System;
using System.Globalization;
using System.Resources;
using System.Threading;

public class Example
{
    public static void Main()
    {
        // Create array of supported cultures
        string[] cultures = { "en-CA", "en-US", "fr-FR", "ru-RU" };
        Random rnd = new Random();
        int cultureNdx = rnd.Next(0, cultures.Length);
        CultureInfo originalCulture = Thread.CurrentThread.CurrentCulture;
        ResourceManager rm = new ResourceManager("Greetings", typeof(Example).Assembly);
        try
        {
            CultureInfo newCulture = new CultureInfo(cultures[cultureNdx]);
            Thread.CurrentThread.CurrentCulture = newCulture;
            Thread.CurrentThread.CurrentUICulture = newCulture;
            string greeting = String.Format("The current culture is {0}.\n{1}",
                                            Thread.CurrentThread.CurrentUICulture.Name,
                                            rm.GetString("HelloString"));
            Console.WriteLine(greeting);
        }
        catch (CultureNotFoundException e)
        {
            Console.WriteLine($"Unable to instantiate culture {e.InvalidCultureName}");
        }
        finally
        {
            Thread.CurrentThread.CurrentCulture = originalCulture;
            Thread.CurrentThread.CurrentUICulture = originalCulture;
        }
    }
}
// The example displays output like the following:
//       The current culture is ru-RU.
//       Всем привет!

Imports System.Globalization
Imports System.Resources
Imports System.Threading

Module Example
   Sub Main()
      ' Create array of supported cultures
      Dim cultures() As String = {"en-CA", "en-US", "fr-FR", "ru-RU" }
      Dim rnd As New Random()
      Dim cultureNdx As Integer = rnd.Next(0, cultures.Length)
      Dim originalCulture As CultureInfo = Thread.CurrentThread.CurrentCulture
      Dim rm As New ResourceManager("Greetings", GetType(Example).Assembly)
      Try
         Dim newCulture As New CultureInfo(cultures(cultureNdx))
         Thread.CurrentThread.CurrentCulture = newCulture
         Thread.CurrentThread.CurrentUICulture = newCulture
         Dim greeting As String = String.Format("The current culture is {0}.{1}{2}",
                                                Thread.CurrentThread.CurrentUICulture.Name,
                                                vbCrLf, rm.GetString("HelloString"))

         Console.WriteLine(greeting)
      Catch e As CultureNotFoundException
         Console.WriteLine("Unable to instantiate culture {0}", e.InvalidCultureName)
      Finally
         Thread.CurrentThread.CurrentCulture = originalCulture
         Thread.CurrentThread.CurrentUICulture = originalCulture
      End Try
   End Sub
End Module
' The example displays output like the following:
'       The current culture is ru-RU.
'       Всем привет!

Para compilar este exemplo, crie um ficheiro batch (.bat) que contenha os seguintes comandos e execute-o a partir da linha de comandos. Se você estiver usando C#, especifique csc em vez de vbc e Example.cs em vez de Example.vb.

resgen Greetings.txt
vbc Example.vb /resource:Greetings.resources

resgen Greetings.fr-FR.txt
Md fr-FR
al /embed:Greetings.fr-FR.resources /culture:fr-FR /out:fr-FR\Example.resources.dll

resgen Greetings.ru-RU.txt
Md ru-RU
al /embed:Greetings.ru-RU.resources /culture:ru-RU /out:ru-RU\Example.resources.dll

Recuperar recursos

Você chama os métodos GetObject(String) e GetString(String) para acessar um recurso específico. Você também pode chamar o método GetStream(String) para recuperar recursos que não sejam de cadeia de caracteres como uma matriz de bytes. Por padrão, em um aplicativo que tem recursos localizados, esses métodos retornam o recurso para a cultura determinada pela cultura atual da interface do usuário do thread que fez a chamada. Consulte a seção anterior, ResourceManager e recursos específicos da cultura, para obter mais informações sobre como a cultura UI atual de um tópico é definida. Se o gerenciador de recursos não conseguir localizar o recurso para a cultura da interface do usuário do thread atual, ele usará um processo de fallback para recuperar o recurso especificado. Se o gerenciador de recursos não conseguir encontrar recursos localizados, ele usará os recursos da cultura padrão. Para obter mais informações sobre regras de substituição de recursos, consulte a seção "Processo de Substituição de Recursos" do artigo Empacotamento e Implantação de Recursos.

O exemplo a seguir usa o método GetString para recuperar recursos específicos da cultura. Consiste em recursos compilados a partir de arquivos .txt para as culturas inglesa (en), francesa (França) (fr-FR) e russa (Rússia) (ru-RU). O exemplo altera a cultura atual e a cultura atual da interface do usuário para inglês (Estados Unidos), francês (França), russo (Rússia) e sueco (Suécia). Em seguida, ele chama o método GetString para recuperar a cadeia de caracteres localizada, que ele exibe junto com o dia e o mês atuais. Observe que a saída exibe a cadeia de caracteres localizada apropriada, exceto quando a cultura atual da interface do usuário é sueca (Suécia). Como os recursos do idioma sueco não estão disponíveis, o aplicativo usa os recursos da cultura padrão, que é o inglês.

O exemplo requer os arquivos de recursos baseados em texto listados na tabela a seguir. Cada um tem um único recurso de cadeia de caracteres chamado DateStart.

Aqui está o código-fonte para o exemplo (ShowDate.vb para a versão do Visual Basic ou ShowDate.cs para a versão C# do código).

using System;
using System.Globalization;
using System.Resources;
using System.Threading;

[assembly: NeutralResourcesLanguage("en")]

public class ShowDateEx
{
    public static void Main()
    {
        string[] cultureNames = { "en-US", "fr-FR", "ru-RU", "sv-SE" };
        ResourceManager rm = new ResourceManager("DateStrings",
                                                 typeof(Example).Assembly);

        foreach (var cultureName in cultureNames)
        {
            CultureInfo culture = CultureInfo.CreateSpecificCulture(cultureName);
            Thread.CurrentThread.CurrentCulture = culture;
            Thread.CurrentThread.CurrentUICulture = culture;

            Console.WriteLine($"Current UI Culture: {CultureInfo.CurrentUICulture.Name}");
            string dateString = rm.GetString("DateStart");
            Console.WriteLine($"{dateString} {DateTime.Now:M}.\n");
        }
    }
}
// The example displays output similar to the following:
//       Current UI Culture: en-US
//       Today is February 03.
//       
//       Current UI Culture: fr-FR
//       Aujourd'hui, c'est le 3 février
//       
//       Current UI Culture: ru-RU
//       Сегодня февраля 03.
//       
//       Current UI Culture: sv-SE
//       Today is den 3 februari.

Imports System.Globalization
Imports System.Resources
Imports System.Threading

<Assembly:NeutralResourcesLanguage("en")>

Module Example5
    Public Sub Main()
        Dim cultureNames() As String = {"en-US", "fr-FR", "ru-RU", "sv-SE"}
        Dim rm As New ResourceManager("DateStrings",
                                    GetType(Example5).Assembly)

        For Each cultureName In cultureNames
            Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture(cultureName)
            Thread.CurrentThread.CurrentCulture = culture
            Thread.CurrentThread.CurrentUICulture = culture

            Console.WriteLine("Current UI Culture: {0}",
                           CultureInfo.CurrentUICulture.Name)
            Dim dateString As String = rm.GetString("DateStart")
            Console.WriteLine("{0} {1:M}.", dateString, Date.Now)
            Console.WriteLine()
        Next
    End Sub
End Module
' The example displays output similar to the following:
'       Current UI Culture: en-US
'       Today is February 03.
'       
'       Current UI Culture: fr-FR
'       Aujourd'hui, c'est le 3 février
'       
'       Current UI Culture: ru-RU
'       Сегодня февраля 03.
'       
'       Current UI Culture: sv-SE
'       Today is den 3 februari.

Para compilar este exemplo, crie um ficheiro batch que contenha os seguintes comandos e execute-o a partir da linha de comandos. Se você estiver usando C#, especifique csc em vez de vbc e showdate.cs em vez de showdate.vb.

resgen DateStrings.txt
vbc showdate.vb /resource:DateStrings.resources

md fr-FR
resgen DateStrings.fr-FR.txt
al /out:fr-FR\Showdate.resources.dll /culture:fr-FR /embed:DateStrings.fr-FR.resources

md ru-RU
resgen DateStrings.ru-RU.txt
al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.resources

Há duas maneiras de recuperar os recursos de uma cultura específica diferente da cultura atual da interface do usuário:

• Você pode chamar o método GetString(String, CultureInfo), GetObject(String, CultureInfo)ou GetStream(String, CultureInfo) para recuperar um recurso para uma cultura específica. Se um recurso localizado não puder ser encontrado, o gerenciador de recursos usará o processo de fallback de recursos para localizar um recurso apropriado.
• Você pode chamar o método GetResourceSet para obter um objeto ResourceSet que representa os recursos para uma cultura específica. Na chamada de método, você pode determinar se o gerenciador de recursos investiga culturas pai se não conseguir encontrar recursos localizados ou se simplesmente retorna aos recursos da cultura padrão. Em seguida, você pode usar os métodos ResourceSet para acessar os recursos (localizados para essa cultura) pelo nome ou para enumerar os recursos no conjunto.

Manipular exceções MissingManifestResourceException e MissingSatelliteAssemblyException

Se o utilizador tentar recuperar um recurso específico, mas o gerenciador de recursos não conseguir encontrar esse recurso e nenhuma cultura padrão tiver sido definida ou os recursos da cultura padrão não puderem ser localizados, o gerenciador de recursos lançará uma exceção MissingManifestResourceException se este espera encontrar os recursos na assemblagem principal ou uma MissingSatelliteAssemblyException se este espera encontrar os recursos numa assemblagem satélite. Observe que a exceção é lançada quando você chama um método de recuperação de recursos, como GetString ou GetObject, e não quando você instancia um objeto ResourceManager.

A exceção é normalmente lançada nas seguintes condições:

• Um arquivo de recurso apropriado ou um conjunto satélite não existe. Se o gerenciador de recursos espera que os recursos padrão do aplicativo sejam incorporados no assembly do aplicativo principal, eles estão ausentes. Se o atributo NeutralResourcesLanguageAttribute indicar que os recursos padrão do aplicativo residem em um assembly satélite, esse assembly não poderá ser encontrado. Ao compilar seu aplicativo, certifique-se de que os recursos estejam incorporados no assembly principal ou que o assembly satélite necessário seja gerado e nomeado adequadamente. Seu nome deve assumir a forma appName.resources.dll, e deve estar localizado em um diretório com o nome da cultura cujos recursos ele contém.

• Seu aplicativo não tem uma cultura padrão ou neutra definida. Adicione o atributo NeutralResourcesLanguageAttribute a um arquivo de código-fonte ou ao arquivo de informações do projeto (AssemblyInfo.vb para um aplicativo Visual Basic ou AssemblyInfo.cs para um aplicativo C#).

• O parâmetro baseName no construtor ResourceManager(String, Assembly) não especifica o nome de um arquivo .resources. O nome deve incluir o namespace totalmente qualificado do arquivo de recurso, mas não sua extensão de nome de arquivo. Normalmente, os arquivos de recursos criados no Visual Studio incluem nomes de namespace, mas os arquivos de recursos criados e compilados no prompt de comando não. Você pode determinar os nomes dos arquivos .resources incorporados compilando e executando o seguinte utilitário. Esta é uma aplicação de consola que aceita o nome de um assembly principal ou satélite como um parâmetro de linha de comando. Ele exibe as cadeias de caracteres que devem ser fornecidas como o parâmetro baseName para que o gerenciador de recursos possa identificar corretamente o recurso.

  using System;
  using System.IO;
  using System.Reflection;
  
  public class Example0
  {
     public static void Main()
     {
        if (Environment.GetCommandLineArgs().Length == 1) { 
           Console.WriteLine("No filename.");
           return;
        }
        
        string filename = Environment.GetCommandLineArgs()[1].Trim();
        // Check whether the file exists.
        if (! File.Exists(filename)) {
           Console.WriteLine($"{filename} does not exist.");
           return;
        }   
        
        // Try to load the assembly.
        Assembly assem = Assembly.LoadFrom(filename);
        Console.WriteLine($"File: {filename}");
           
        // Enumerate the resource files.
        string[] resNames = assem.GetManifestResourceNames();
        if (resNames.Length == 0)
           Console.WriteLine("   No resources found.");
  
        foreach (var resName in resNames)
           Console.WriteLine($"   Resource: {resName.Replace(".resources", "")}");
  
        Console.WriteLine();
     }
  }
  

  Imports System.IO
  Imports System.Reflection
  Imports System.Resources
  
  Module Example
     Public Sub Main()
        If Environment.GetCommandLineArgs.Length = 1 Then 
           Console.WriteLine("No filename.")
           Exit Sub
        End If
        Dim filename As String = Environment.GetCommandLineArgs(1).Trim()
        ' Check whether the file exists.
        If Not File.Exists(filename) Then
           Console.WriteLine("{0} does not exist.", filename)
           Exit Sub
        End If   
        
        ' Try to load the assembly.
        Dim assem As Assembly = Assembly.LoadFrom(filename)
        Console.WriteLine("File: {0}", filename)
           
        ' Enumerate the resource files.
        Dim resNames() As String = assem.GetManifestResourceNames()
        If resNames.Length = 0 Then
           Console.WriteLine("   No resources found.")
        End If
        For Each resName In resNames
           Console.WriteLine("   Resource: {0}", resName.Replace(".resources", ""))
        Next
        Console.WriteLine()
     End Sub
  End Module
  

Se você estiver alterando a cultura atual do seu aplicativo explicitamente, também deve lembrar que o gerenciador de recursos recupera um conjunto de recursos com base no valor da propriedade CultureInfo.CurrentUICulture e não na propriedade CultureInfo.CurrentCulture. Normalmente, se você alterar um valor, também deverá alterar o outro.

Controle de versão de recursos

Como o assembly principal que contém os recursos padrão de um aplicativo é separado dos assemblies satélite do aplicativo, você pode lançar uma nova versão do assembly principal sem reimplantar os assemblies satélite. Use o atributo SatelliteContractVersionAttribute para usar assemblies satélite existentes e instrua o gestor de recursos a não os implantar novamente com uma nova versão do assembly principal.

Para obter mais informações sobre o suporte ao controlo de versões para assemblies satélite, consulte o artigo Recuperando recursos.

<satelliteassemblies> Nodo de ficheiro de configuração

Para executáveis que são implantados e executados a partir de um site (arquivos HREF .exe), o objeto ResourceManager pode procurar por assemblies satélite na internet, o que pode prejudicar o desempenho da sua aplicação. Para eliminar o problema de desempenho, você pode limitar essa sondagem aos assemblies satélite implantados com seu aplicativo. Para fazer isso, crie um nó <satelliteassemblies> no arquivo de configuração do aplicativo para especificar que implantou um conjunto específico de culturas para seu aplicativo e que o objeto ResourceManager não deve tentar investigar nenhuma cultura que não esteja listada nesse nó.

No arquivo de configuração do seu aplicativo, crie uma seção semelhante à seguinte:

<?xml version ="1.0"?>
<configuration>
  <satelliteassemblies>
    <assembly name="MainAssemblyName, Version=versionNumber, Culture=neutral, PublicKeyToken=null|yourPublicKeyToken">
      <culture>cultureName1</culture>
      <culture>cultureName2</culture>
      <culture>cultureName3</culture>
    </assembly>
  </satelliteassemblies>
</configuration>

Edite essas informações de configuração da seguinte maneira:

• Especifique um ou mais nós <assembly> para cada assembly principal que implanta, onde cada nó especifica um nome de assembly totalmente qualificado. Especifique o nome do assembly principal no lugar de MainAssemblyNamee especifique os valores de atributo Version, PublicKeyTokene Culture que correspondem ao assembly principal.

  Para o atributo Version, especifique o número da versão do assembly. Por exemplo, a primeira versão do seu conjunto pode ser o número de versão 1.0.0.0.

  Para o atributo PublicKeyToken, especifique a palavra-chave null se você não tiver assinado seu assembly com um nome forte ou especifique seu token de chave pública se tiver assinado seu assembly.

  Para o atributo Culture, especifique a palavra-chave neutral para designar o assembly principal e fazer com que a classe ResourceManager probe apenas as culturas listadas nos nós <culture>.

  Para obter mais informações sobre nomes de assembly totalmente qualificados, consulte o artigo intitulado Nomes de assembly. Para obter mais informações sobre assemblies com nome forte, consulte o artigo Criar e usar assemblies com nome forte.

• Especifique um ou mais nós <culture> com um nome de cultura específico, como "fr-FR", ou um nome de cultura neutro, como "fr".

Se forem necessários recursos para qualquer assembly não listado no nó <satelliteassemblies>, a classe ResourceManager investigará culturas usando regras de sondagem padrão.

Aplicações do Windows 8.x

Para aplicativos do Windows 8.x, a classe ResourceManager recupera recursos de arquivos de índice de recursos de pacote (PRI). Um único arquivo PRI (o arquivo PRI do pacote de aplicativo) contém os recursos para a cultura padrão e quaisquer culturas localizadas. Use o utilitário MakePRI para criar um arquivo PRI a partir de um ou mais arquivos de recurso que estão no formato de recurso XML (.resw). Para recursos incluídos em um projeto do Visual Studio, o Visual Studio lida com o processo de criação e empacotamento do arquivo PRI automaticamente. Em seguida, você pode usar a classe .NET ResourceManager para acessar os recursos do aplicativo ou da biblioteca.

Você pode instanciar um objeto ResourceManager para um aplicativo do Windows 8.x da mesma forma que faz para um aplicativo da área de trabalho.

Em seguida, você pode acessar os recursos de uma cultura específica passando o nome do recurso a ser recuperado para o método GetString(String). Por padrão, esse método retorna o recurso para a cultura determinada pela cultura atual da interface do usuário do thread que fez a chamada. Você também pode recuperar os recursos para uma cultura específica passando o nome do recurso e um objeto CultureInfo que representa a cultura cujo recurso deve ser recuperado para o método GetString(String, CultureInfo). Se o recurso para a cultura atual da interface do usuário ou a cultura especificada não puder ser encontrado, o gerenciador de recursos usará uma lista de fallback de idioma da interface do usuário para localizar um recurso adequado.

Exemplos

O exemplo a seguir demonstra como usar uma cultura explícita e a cultura de interface do usuário atual implícita para obter recursos de cadeia de caracteres de um assembly principal e um assembly satélite. Para obter mais informações, consulte a seção "Locais de diretório para assemblies satélite não instalados no cache de assembly global" do tópico Criando assemblies satélite.

Para executar este exemplo:

1. No diretório do aplicativo, crie um arquivo chamado rmc.txt que contenha as seguintes cadeias de caracteres de recursos:

   day=Friday
   year=2006
   holiday="Cinco de Mayo"
   

2. Use o Resource File Generator para gerar o arquivo de recurso rmc.resources a partir do arquivo de entrada rmc.txt da seguinte maneira:

   resgen rmc.txt
   

3. Crie um subdiretório do diretório do aplicativo e nomeie-o como "es-MX". Este é o nome da cultura do assembly satélite que você criará nas próximas três etapas.

4. Crie um arquivo chamado rmc.es-MX.txt no diretório es-MX que contenha as seguintes cadeias de caracteres de recursos:

   day=Viernes
   year=2006
   holiday="Cinco de Mayo"
   

5. Use o Resource File Generator para gerar o arquivo de recurso rmc.es-MXa partir do arquivo de entrada rmc.es-MX.txt da seguinte maneira:

   resgen rmc.es-MX.txt
   

6. Suponha que o nome do arquivo para este exemplo é rmc.vb ou rmc.cs. Copie o seguinte código-fonte para um arquivo. Em seguida, compile-o e incorpore o ficheiro de recursos do assembly principal, rmc.resources, no assembly executável. Se você estiver usando o compilador do Visual Basic, a sintaxe é:

   vbc rmc.vb /resource:rmc.resources
   

   A sintaxe correspondente para o compilador C# é:

   csc /resource:rmc.resources rmc.cs
   

7. Use o Assembly Linker para criar um assembly satélite. Se o nome base da aplicação for rmc, o nome do assembly satélite deverá ser rmc.resources.dll. O conjunto satélite deve ser criado no diretório es-MX. Se es-MX for o diretório atual, use este comando:

   al /embed:rmc.es-MX.resources /c:es-MX /out:rmc.resources.dll
   

8. Execute rmc.exe para obter e exibir as cadeias de caracteres de recursos incorporados.

   using System;
   using System.Globalization;
   using System.Resources;
   
   class Example2
   {
       public static void Main()
       {
           string day;
           string year;
           string holiday;
           string celebrate = "{0} will occur on {1} in {2}.\n";
   
           // Create a resource manager.
           ResourceManager rm = new ResourceManager("rmc",
                                    typeof(Example).Assembly);
   
           Console.WriteLine("Obtain resources using the current UI culture.");
   
           // Get the resource strings for the day, year, and holiday
           // using the current UI culture.
           day = rm.GetString("day");
           year = rm.GetString("year");
           holiday = rm.GetString("holiday");
           Console.WriteLine(celebrate, holiday, day, year);
   
           // Obtain the es-MX culture.
           CultureInfo ci = new CultureInfo("es-MX");
   
           Console.WriteLine("Obtain resources using the es-MX culture.");
   
           // Get the resource strings for the day, year, and holiday
           // using the specified culture.
           day = rm.GetString("day", ci);
           year = rm.GetString("year", ci);
           holiday = rm.GetString("holiday", ci);
           // ---------------------------------------------------------------
           // Alternatively, comment the preceding 3 code statements and
           // uncomment the following 4 code statements:
           // ----------------------------------------------------------------
           // Set the current UI culture to "es-MX" (Spanish-Mexico).
           //    Thread.CurrentThread.CurrentUICulture = ci;
   
           // Get the resource strings for the day, year, and holiday
           // using the current UI culture. Use those strings to
           // display a message.
           //    day  = rm.GetString("day");
           //    year = rm.GetString("year");
           //    holiday = rm.GetString("holiday");
           // ---------------------------------------------------------------
   
           // Regardless of the alternative that you choose, display a message
           // using the retrieved resource strings.
           Console.WriteLine(celebrate, holiday, day, year);
       }
   }
   /*
   This example displays the following output:
   
      Obtain resources using the current UI culture.
      "5th of May" will occur on Friday in 2006.
   
      Obtain resources using the es-MX culture.
      "Cinco de Mayo" will occur on Viernes in 2006.
   */
   

   Imports System.Resources
   Imports System.Reflection
   Imports System.Threading
   Imports System.Globalization
   
   Class Example4
       Public Shared Sub Main()
           Dim day As String
           Dim year As String
           Dim holiday As String
           Dim celebrate As String = "{0} will occur on {1} in {2}." & vbCrLf
   
           ' Create a resource manager. 
           Dim rm As New ResourceManager("rmc", GetType(Example4).Assembly)
   
           Console.WriteLine("Obtain resources using the current UI culture.")
   
           ' Get the resource strings for the day, year, and holiday 
           ' using the current UI culture. 
           day = rm.GetString("day")
           year = rm.GetString("year")
           holiday = rm.GetString("holiday")
           Console.WriteLine(celebrate, holiday, day, year)
   
           ' Obtain the es-MX culture.
           Dim ci As New CultureInfo("es-MX")
   
           Console.WriteLine("Obtain resources using the es-MX culture.")
   
           ' Get the resource strings for the day, year, and holiday 
           ' using the es-MX culture.  
           day = rm.GetString("day", ci)
           year = rm.GetString("year", ci)
           holiday = rm.GetString("holiday", ci)
   
           ' ---------------------------------------------------------------
           ' Alternatively, comment the preceding 3 code statements and 
           ' uncomment the following 4 code statements:
           ' ----------------------------------------------------------------
           ' Set the current UI culture to "es-MX" (Spanish-Mexico).
           '    Thread.CurrentThread.CurrentUICulture = ci
           ' Get the resource strings for the day, year, and holiday 
           ' using the current UI culture. 
           '    day  = rm.GetString("day")
           '    year = rm.GetString("year")
           '    holiday = rm.GetString("holiday")
           ' ---------------------------------------------------------------
   
           ' Regardless of the alternative that you choose, display a message 
           ' using the retrieved resource strings.
           Console.WriteLine(celebrate, holiday, day, year)
       End Sub
   End Class
   ' This example displays the following output:
   'Obtain resources using the current UI culture.
   '"5th of May" will occur on Friday in 2006.
   '
   'Obtain resources using the es-MX culture.
   '"Cinco de Mayo" will occur on Viernes in 2006.