ResourceManager Class

Updated: March 2012

Provides convenient access to culture-specific resources at run time.

Namespace:  System.Resources
Assembly:  mscorlib (in mscorlib.dll)

[SerializableAttribute]
[ComVisibleAttribute(true)]
public class ResourceManager

The ResourceManager class retrieves resources from binary resource (.resources) files. Typically, these resource files are embedded in an assembly either by a language compiler or by the Assembly Linker (AL.exe), although the CreateFileBasedResourceManager method allows a ResourceManager object to retrieve resources directly from a .resources file that is not embedded in an assembly. To create a .resources file from a resource file in either text (.txt) or XML resource (.resx) format, you compile it with the Resource File Generator (Resgen.exe). For .resx files that are included in a Visual Studio project, Visual Studio handles compilation automatically as part of the build process.

The ResourceManager class looks up culture-specific resources, provides resource fallback when a localized resource does not exist, and supports resource serialization.

Using the methods of ResourceManager, a caller can access the resources for a particular culture using the GetObject and GetString methods. By default, these methods return the resource for the culture determined by the current cultural settings of the thread that made the call. (See Thread.CurrentUICulture for more information.) A caller can use the ResourceManager.GetResourceSet method to obtain a ResourceSet, which represents the resources for a particular culture, ignoring culture fallback rules. You can then use the ResourceSet to access the resources, localized for that culture, by name.

Ideally, you should create resources for every language, or at least a meaningful subset of the language. The resource file names follow the naming convention basename.cultureName.resources, where basename is the name of the application or the name of a class, depending on the level of detail you want. The CultureInfo 's Name property is used to determine the cultureName. A resource for the neutral culture (returned by InvariantCulture) should be named basename.resources.

For example, suppose that an assembly has several resources in a resource file with the basename "MyResources". These resource files will have names such as "MyResources.ja-JP.resources", "MyResources.de.resources", "MyResources.zh-CHS.resources", or "MyResources.fr-BE.resources", which contain resources respectively for Japanese, German, simplified Chinese, and French (Belgium). The default resource file should be named MyResources.resources. The culture-specific resource files are commonly packaged in satellite assemblies for each culture. The default resource file should be in your main assembly.

Now suppose that a ResourceManager has been created to represent the resources with this basename. Using the ResourceManager, you can obtain a ResourceSet that encapsulates "MyResources.ja-JP.resources" by calling GetResourceSet(new CultureInfo ("ja-JP"), TRUE, FALSE). Or, if you know that "MyResources" contains a resource named "TOOLBAR_ICON", you can obtain the value of that resource localized for Japan by calling GetObject("TOOLBAR_ICON", new CultureInfo("ja-JP")).

While not strictly necessary for the most basic uses of the ResourceManager, publicly shipping assemblies should use the SatelliteContractVersionAttribute to support versioning your main assembly without redeploying your satellites, and the NeutralResourcesLanguageAttribute to avoid looking up a satellite assembly that might never exist.

For more information about versioning support for satellite assemblies, see Retrieving Resources in Satellite Assemblies. To learn more about creating satellite assemblies, see Creating Satellite Assemblies. For assistance with localization of Windows Forms dialogs, see the Windows Forms Resource Editor (Winres.exe) tool in the Windows Software Development Kit (SDK).

To learn more about setting up and creating resources, see Resources in Applications.

Caution noteCaution:

Using standalone .resources files in an ASP.NET application will break XCOPY deployment, because the resources remain locked until they are explicitly released by the ReleaseAllResources method. If you want to deploy resources into ASP.NET applications, you should compile your .resources into satellite assemblies.

Caution noteCaution:

Resources marked as private are accessible only in the assembly in which they are placed. Because a satellite assembly contains no code, resources private to it become unavailable through any mechanism. Therefore, resources in satellite assemblies should always be public so that they are accessible from your main assembly. Resources embedded in your main assembly are accessible to your main assembly, whether private or public.

<satelliteassemblies> Configuration File Node

For executables deployed and run from a Web site (HREF .exe files), the ResourceManager class may probe for satellite assemblies over the Web, which can hurt your application's performance. You can limit this probing to the satellite assemblies that you have deployed with your application, which eliminates the performance problem. To do this, you create a <satelliteassemblies> node in the application configuration file to specify that you have deployed a specific set of cultures for your application, and that the ResourceManager class should not attempt to probe for any culture that is not listed in that node.

NoteNote:

The preferred alternative to creating a <satelliteassemblies> node is to use the ClickOnce Deployment Manifest feature.

Create a configuration file section similar to the following code example:

<?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>

In your configuration file, do the following:

  • Specify one or more <assembly> nodes for each main assembly that you deploy, where the <assembly> node attribute specifies a fully qualified assembly name. Specify the name of your main assembly in place of MainAssemblyName, and specify the Version, PublicKeyToken, and Culture attribute values that correspond to your main assembly.

    For the Version attribute, specify the version number of your assembly. For example, the first release of your assembly might be version number 1.0.0.0.

    For the PublicKeyToken attribute, specify the keyword "null" if you have not signed your assembly with a strong name, or specify your public key token if you have signed your assembly.

    For the Culture attribute, specify the keyword "neutral" to designate the main assembly and cause the ResourceManager class to probe only for the cultures listed in the <culture> nodes.

    For more information about fully qualified assembly names, see Assembly Names. For more information about strong-named assemblies, see Creating and Using Strong-Named Assemblies.

  • Specify one or more <culture> nodes with a specific culture name, such as "fr-FR", or a neutral culture name, such as "fr".

    Caution noteCaution:

    In version 1.1 of the .NET Framework, you must add the following configuration section handler to your configuration file. However, because the .NET Framework version 2.0 does not support this handler, you must remove it from your configuration file if you upgrade from version 1.1 to version 2.0 of the .NET Framework.

       <configSections>
          <section name="satelliteassemblies" type="System.Configuration.IgnoreSectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowLocation="false" />
       </configSections>
    

If resources are needed for any assembly not listed under the <satelliteassemblies> node, the ResourceManager class probes for cultures using standard probing rules.

The following example demonstrates how to use an explicit culture and the implicit current UI culture to obtain string resources from a main assembly and a satellite assembly. For more information, see the "Directory Locations for Satellite Assemblies Not Installed in the Global Assembly Cache" section of the Creating Satellite Assemblies topic.

To run this example:

  1. In the app directory, create a file named rmc.txt that contains the following resource strings:

    day=Friday
    year=2006
    holiday="Cinco de Mayo"
    
  2. Use the Resource File Generator to generate the rmc.resources resource file from the rmc.txt input file as follows:

    resgen rmc.txt
    
  3. Create a subdirectory of the app directory and name it "es-MX". This is the culture name of the satellite assembly that you will create in the next three steps.

  4. Create a file named rmc.es-MX.txt in the es-MX directory that contains the following resource strings:

    day=Viernes
    year=2006
    holiday="Cinco de Mayo"
    
  5. Use the Resource File Generator to generate the rmc.es-MX.resources resource file from the rmc.es-MX.txt input file as follows:

    resgen rmc.es-MX.txt
    
  6. Assume that the file name for this example is rmc.vb or rmc.cs. Copy the following source code into a file. Then compile it and embed the main assembly resource file, rmc.resources, in the executable assembly. If you are using the Visual Basic compiler, the syntax is:

    vbc rmc.vb /resource:rmc.resources
    

    The corresponding syntax for the C# compiler is:

    csc rmc.cs /resource:rmc.resources
    
  7. Use the Assembly Linker to create a satellite assembly. If the base name of the app is rmc, the satellite assembly name must be rmc.resources.dll. The satellite assembly should be created in the es-MX directory. If es-MX is the current directory, use this command:

    al /embed:rmc.es-MX.resources /c:es-MX /out:rmc.resources.dll 
    
  8. Run rmc.exe to obtain and display the embedded resource strings.

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

class Example 
{
    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.
*/

This type is thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Date

History

Reason

March 2012

Replaced the example.

Information enhancement.

January 2011

In the Remarks section, noted that Resource Manager works with .resources files only.

Customer feedback.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft