Classe System.Resources.NeutralResourcesLanguageAttribute

Este artigo fornece comentários complementares à documentação de referência para esta API.

Em aplicativos da área de trabalho, o NeutralResourcesLanguageAttribute atributo informa ao gerenciador de recursos a cultura padrão de um aplicativo e a localização de seus recursos. Por padrão, os recursos são inseridos no assembly principal do aplicativo e você pode usar o atributo da seguinte maneira. Esta instrução especifica que o inglês (Estados Unidos) é a cultura padrão do aplicativo.

[assembly: NeutralResourcesLanguage("en-US")]

<Assembly:NeutralResourcesLanguage("en-US")>

Você também pode usar o NeutralResourcesLanguageAttribute atributo para indicar onde ResourceManager pode encontrar os recursos da cultura padrão fornecendo um UltimateResourceFallbackLocation valor de enumeração na instrução de atributo. Isso é feito mais comumente para indicar que os recursos residem em um conjunto satélite. Por exemplo, a instrução a seguir especifica que Inglês (Estados Unidos) é a cultura padrão ou neutra do aplicativo e que seus recursos residem em um assembly secundário. O ResourceManager objeto os procurará em um subdiretório chamado en-US.

[assembly: NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)]

<Assembly:NeutralResourcesLanguage("en-US", UltimateResourceFallbackLocation.Satellite)>

O atributo executa duas funções:

• Se os recursos da cultura padrão forem inseridos no assembly principal do aplicativo e ResourceManager tiverem que recuperar recursos que pertencem à mesma cultura que a cultura padrão, ele ResourceManager usará automaticamente os recursos localizados no assembly principal em vez de procurar um assembly satélite. Isso contorna a investigação de assembly usual, melhora o desempenho da pesquisa para o primeiro recurso que você carrega e pode reduzir o conjunto de trabalho. Consulte Empacotamento e Implantação de Recursos para o processo ResourceManager usado para procurar por arquivos de recursos.

• Se os recursos da cultura padrão estiverem localizados em um assembly satélite em vez do assembly do aplicativo principal, o atributo NeutralResourcesLanguageAttribute especifica a cultura e o diretório do qual o runtime pode carregar os recursos.

Aplicativos da Windows 8.x Store

Em aplicativos da Windows 8.x Store cujos recursos são carregados e recuperados usando a classe ResourceManager, o atributo NeutralResourcesLanguageAttribute define a cultura neutra cujos recursos são usados no caso de uma investigação com falha. Ele não especifica o local dos recursos. Por padrão, ResourceManager usa o arquivo PRI (índice de recursos de pacote) do aplicativo para localizar os recursos da cultura padrão. A cultura neutra definida pelo NeutralResourcesLanguageAttribute atributo é adicionada ao final da lista de idiomas da interface do usuário para simular esse efeito.

Se você carregar e recuperar recursos usando a classeWindows Runtime Windows.ApplicationModel.Resources.ResourceLoader ou os tipos no namespace Windows.ApplicationModel.Resources.Core , o NeutralResourcesLanguageAttribute atributo será ignorado.

Exemplos

O exemplo a seguir usa um simples aplicativo "Olá, Mundo" para ilustrar o uso do atributo NeutralResourcesLanguageAttribute para definir uma cultura padrão ou de fallback. Requer a criação de arquivos de recurso separados para as culturas inglês (en), inglês (Estados Unidos) (en-US) e francês (França) (fr-FR). Veja a seguir o conteúdo de um arquivo de texto chamado ExampleResources.txt para a cultura inglesa.

# Resources for the default (en) culture.
Greeting=Hello

Para usar o arquivo de recurso em um aplicativo, você deve usar o Gerador de Arquivos de Recurso (Resgen.exe) para converter o arquivo de seu formato de texto (.txt) em um formato binário (.resources) da seguinte maneira:

resgen ExampleResources.txt

Quando o aplicativo for compilado, o arquivo de recurso binário será inserido no assembly principal do aplicativo.

O seguinte mostra o conteúdo de um arquivo de texto chamado ExampleResources.en-US.txt que fornece recursos para a cultura inglesa (Estados Unidos).

# Resources for the en-US culture.
Greeting=Hi

O arquivo de texto pode ser convertido em um arquivo de recursos binários usando o Gerador de Arquivos de Recurso (ResGen.exe) na linha de comando da seguinte maneira:

resgen ExampleResources.en-US.txt ExampleResources.en-US.resources

Em seguida, o arquivo de recurso binário deve ser compilado em um assembly usando o Assembly Linker (Al.exe) e colocado no subdiretório en-US do diretório do aplicativo emitindo o seguinte comando:

al /t:lib /embed:ExampleResources.en-US.resources /culture:en-US /out:en-us\Example.resources.dll

Veja a seguir o conteúdo de um arquivo de texto chamado ExampleResources.fr-FR.txt que fornece recursos para a cultura francesa (França).

# Resources for the fr-FR culture.
Greeting=Bonjour

O arquivo de texto pode ser convertido em um arquivo de recurso binário usando ResGen.exe na linha de comando da seguinte maneira:

resgen ExampleResources.fr-FR.txt ExampleResources.fr-FR.resources

O arquivo de recursos binários deve então ser compilado em um assembly usando o Assembly Linker e colocado no subdiretório fr-FR do diretório do aplicativo emitindo o seguinte comando:

al /t:lib /embed:ExampleResources.fr-FR.resources /culture:fr-FR /out:fr-FR\Example.resources.dll

O exemplo a seguir fornece o código executável que define a cultura atual, solicita o nome do usuário e exibe uma cadeia de caracteres localizada.

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

[assembly: NeutralResourcesLanguageAttribute("en")]
public class Example
{
    public static void Main()
    {
        // Select the current culture randomly to test resource fallback.
        string[] cultures = { "de-DE", "en-us", "fr-FR" };
        Random rnd = new Random();
        int index = rnd.Next(0, cultures.Length);
        Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultures[index]);
        Console.WriteLine($"The current culture is {CultureInfo.CurrentUICulture.Name}");

        // Retrieve the resource.
        ResourceManager rm = new ResourceManager("ExampleResources",
                                                 typeof(Example).Assembly);
        string greeting = rm.GetString("Greeting");

        Console.Write("Enter your name: ");
        string name = Console.ReadLine();
        Console.WriteLine($"{greeting} {name}!");
    }
}

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

<Assembly:NeutralResourcesLanguageAttribute("en")>

Module Example
   Public Sub Main()
      ' Select the current culture randomly to test resource fallback.
      Dim cultures() As String = { "de-DE", "en-us", "fr-FR" }
      Dim rnd As New Random()
      Dim index As Integer = rnd.Next(0, cultures.Length)
      Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultures(index))      
      Console.WriteLine("The current culture is {0}", 
                        CultureInfo.CurrentUICulture.Name)       

      ' Retrieve the resource.
      Dim rm As New ResourceManager("ExampleResources" , GetType(Example).Assembly)
      Dim greeting As String = rm.GetString("Greeting")
      
      Console.Write("Enter your name: ")
      Dim name As String = Console.ReadLine()
      Console.WriteLine("{0} {1}", greeting, name)
   End Sub
End Module

Ele pode ser compilado usando o seguinte comando no Visual Basic:

vbc Example.vb /resource:ExampleResources.resources

ou usando o seguinte comando em C#:

csc Example.cs /resource:ExampleResources.resources