System.Resources.NeutralResourcesLanguageAttribute 类

  • 项目

本文提供了此 API 参考文档的补充说明。

在桌面应用中，该 NeutralResourcesLanguageAttribute 属性将通知资源管理器应用的默认区域性及其资源的位置。 默认情况下，资源嵌入在主应用程序集中，可以使用如下所示的属性。 此语句指定英语（美国）是应用的默认区域性。

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

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

还可以使用NeutralResourcesLanguageAttribute特性通过提供UltimateResourceFallbackLocation特性语句中的枚举值来指示在何处ResourceManager可以找到默认区域性的资源。 这通常是为了指示资源驻留在附属程序集中。 例如，以下语句指定英语（美国）是应用的默认或中性区域性，并且其资源驻留在附属程序集中。 该 ResourceManager 对象将在名为 en-US 的子目录中查找它们。

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

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

提示

建议始终使用该 NeutralResourcesLanguageAttribute 属性来定义应用的默认区域性。

该属性执行两个角色：

  • 如果默认区域性的资源嵌入在应用的主程序集中，并且 ResourceManager 必须检索与默认区域性属于同一区域性的资源，则 ResourceManager 会自动使用位于主程序集中的资源，而不是搜索附属程序集。 这样可绕过常用程序集探测，提高所加载的第一个资源的查找性能，并可缩小工作集。 请参阅 打包和部署资源 ，了解用于探测资源文件的过程 ResourceManager 。

  • 如果默认区域性的资源位于附属程序集而不是主应用程序集中，则 NeutralResourcesLanguageAttribute 特性指定运行时可从中加载资源的区域性和目录。

Windows 8.x 应用商店应用

在使用 ResourceManager 类加载和检索其资源的 Windows 8.x 应用商店应用中，该 NeutralResourcesLanguageAttribute 属性定义在探测失败时使用其资源的中性区域性。 它不指定资源的位置。 默认情况下， ResourceManager 使用应用的包资源索引 （PRI） 文件查找默认区域性的资源。 属性 NeutralResourcesLanguageAttribute 定义的中性区域性将添加到 UI 语言列表的末尾，以模拟此效果。

如果使用 Windows 运行时Windows.ApplicationModel.Resources.ResourceLoader 类或 Windows.ApplicationModel.Resources.Core 命名空间中的类型加载和检索资源，则NeutralResourcesLanguageAttribute忽略该属性。

示例

以下示例使用简单的“Hello World”应用来说明如何使用 NeutralResourcesLanguageAttribute 该属性来定义默认或回退区域性。 它要求为英语（en）、英语（美国）和法语（法国）（fr-FR）文化创建单独的资源文件。 下面显示了一个名为英语区域性ExampleResources.txt的文本文件的内容。

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

若要在应用中使用资源文件，必须使用 资源文件生成器（Resgen.exe） 将文件从其文本（.txt）格式转换为二进制（.resources）格式，如下所示：

resgen ExampleResources.txt

编译应用后，二进制资源文件将嵌入主应用程序集中。

下面显示了一个名为ExampleResources.en-US.txt的文本文件的内容，该文件为英语（美国）区域性提供资源。

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

可以在命令行中使用 资源文件生成器（ResGen.exe） 将文本文件转换为二进制资源文件，如下所示：

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

然后，应使用 程序集链接器（Al.exe） 将二进制资源文件编译为程序集，并通过发出以下命令将其放置在应用目录的 en-US 子目录中：

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

下面显示了一个名为ExampleResources.fr-FR.txt的文本文件的内容，该文件为法语（法国）区域性提供资源。

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

可以使用命令行中的ResGen.exe将文本文件转换为二进制资源文件，如下所示：

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

然后，应使用程序集链接器将二进制资源文件编译为程序集，并通过发出以下命令将文件放置在应用目录的 fr-FR 子目录中：

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

以下示例提供可执行代码，用于设置当前区域性、提示输入用户名并显示本地化字符串。

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 {0}",
                          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("{0} {1}!", 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

可以在 Visual Basic 中使用以下命令编译它：

vbc Example.vb /resource:ExampleResources.resources

或在 C# 中使用以下命令：

csc Example.cs /resource:ExampleResources.resources