Examples

The following example uses a simple "Hello World" app to illustrate the use of the NeutralResourcesLanguageAttribute attribute to define a default or fallback culture. It requires the creation of separate resource files for the English (en), English (United States) (en-US), and French (France) (fr-FR) cultures. The following shows the contents of a text file named ExampleResources.txt for the English culture.

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

To use the resource file in an app, you must use the Resource File Generator (Resgen.exe) to convert the file from its text (.txt) format to a binary (.resources) format as follows:

resgen ExampleResources.txt

When the app is compiled, the binary resource file will be embedded in the main app assembly.

The following shows the contents of a text file named ExampleResources.en-US.txt that provides resources for the English (United States) culture.

Remarks

Desktop Apps

In desktop apps, the NeutralResourcesLanguageAttribute attribute informs the resource manager of an app's default culture and the location of its resources. By default, resources are embedded in the main app assembly, and you can use the attribute as follows. This statement specifies that the English (United States) is the app's default culture.

using System.Resources;
[assembly:NeutralResourcesLanguage("en-US")]

Imports System.Resources
<Assembly:NeutralResourcesLanguage("en-US")>

You can also use the NeutralResourcesLanguageAttribute attribute to indicate where ResourceManager can find the resources of the default culture by providing an UltimateResourceFallbackLocation enumeration value in the attribute statement. This is most commonly done to indicate that the resources reside in a satellite assembly. For example, the following statement specifies that English (United States) is the app's default or neutral culture and that its resources reside in a satellite assembly. The ResourceManager object will look for them in a subdirectory named en-US.

If the default culture's resources are embedded in the app's main assembly and ResourceManager has to retrieve resources that belong to the same culture as the default culture, the ResourceManager automatically uses the resources located in the main assembly instead of searching for a satellite assembly. This bypasses the usual assembly probe, improves lookup performance for the first resource you load, and can reduce your working set. See Packaging and Deploying Resources for the process ResourceManager uses to probe for resource files.

If the default culture's resources are located in a satellite assembly rather than in the main app assembly, the NeutralResourcesLanguageAttribute attribute specifies the culture and the directory from which the runtime can load the resources.

Windows 8.x Store Apps

In Windows 8.x Store apps whose resources are loaded and retrieved by using the ResourceManager class, the NeutralResourcesLanguageAttribute attribute defines the neutral culture whose resources are used in the event of a failed probe. It does not specify the location of the resources. By default, ResourceManager uses the app's package resource index (PRI) file to locate the resources of the default culture. The neutral culture that is defined by the NeutralResourcesLanguageAttribute attribute is added to the end of the UI language list to simulate this effect.