Article
11/18/2011

ResourceManager Class

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Updated: January 2011

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

Inheritance Hierarchy

System.Object
System.Resources.ResourceManager

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

Syntax

'Declaration
<ComVisibleAttribute(True)> _
Public Class ResourceManager

[ComVisibleAttribute(true)]
public class ResourceManager

The ResourceManager type exposes the following members.

Constructors

	Name	Description
	ResourceManager()	Initializes a new instance of the ResourceManager class with default values.
	ResourceManager(Type)	Creates a ResourceManager that looks up resources in satellite assemblies based on information from the specified Type.
	ResourceManager(String, Assembly)	Initializes a new instance of the ResourceManager class that looks up resources contained in files derived from the specified root name using the given Assembly.
	ResourceManager(String, Assembly, Type)	Initializes a new instance of the ResourceManager class that looks up resources contained in files derived from the specified root name using the given Assembly.

Top

Properties

	Name	Description
	BaseName	Gets the root name of the resource files that the ResourceManager searches for resources.
	IgnoreCase	Gets or sets a Boolean value indicating whether the current instance of ResourceManager allows case-insensitive resource lookups in the GetString and GetObject methods.
	ResourceSetType	Gets the Type of the ResourceSet the ResourceManager uses to construct a ResourceSet object.

Top

Methods

	Name	Description
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before the Object is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetNeutralResourcesLanguage	Returns the CultureInfo for the main assembly's neutral resources by reading the value of the NeutralResourcesLanguageAttribute on a specified Assembly.
	GetObject(String)	Returns the value of the specified Object resource.
	GetObject(String, CultureInfo)	Gets the value of the Object resource localized for the specified culture.
	GetResourceFileName	Generates the name for the resource file for the given CultureInfo.
	GetResourceSet	Gets the ResourceSet for a particular culture.
	GetSatelliteContractVersion	Returns the Version specified by the SatelliteContractVersionAttribute attribute in the given assembly.
	GetStream(String)	Returns an UnmanagedMemoryStream object from the specified resource.
	GetStream(String, CultureInfo)	Returns an UnmanagedMemoryStream object from the specified resource, using the specified culture.
	GetString(String)	Returns the value of the specified String resource.
	GetString(String, CultureInfo)	Gets the value of the String resource localized for the specified culture.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	InternalGetResourceSet	Provides the implementation for finding a ResourceSet.
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ReleaseAllResources	Tells the ResourceManager to call Close on all ResourceSet objects and release all resources.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Fields

	Name	Description
	BaseNameField	Indicates the root name of the resource files that the ResourceManager searches for resources.
	HeaderVersionNumber	A constant readonly value indicating the version of resource file headers that the current implementation of ResourceManager can interpret and produce.
	MagicNumber	Holds the number used to identify resource files.
	MainAssembly	Indicates the main Assembly that contains the resources.

Top

Remarks

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

The ResourceManager class retrieves resources from binary resource (.resources) files. Typically, these resource files are embedded in an assembly at compile time, although the CreateFileBasedResourceManager method allows a ResourceManager object to retrieve resources directly from a .resources file that is not embedded in an assembly.

Note:
Silverlight-based applications do not support resources that are dependent on serialization.

You can use the following types for your resources because they are not based on serialization.

The following types cannot be used as resources:

Any type that is made serializable.
GUID values.
Enumerated values.
A user-defined value type or reference type.

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-Hans.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.

To learn more about setting up and creating resources, see Deployment and Localization.

Caution:
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.

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 ResourceManagerr 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.

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.

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

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

Examples

The following code example demonstrates using an explicit culture and the implicit current UI culture to obtain string resources from a main assembly and a satellite assembly.

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

'
'Perform the following steps to use this code example:
'
'Main assembly:
'1) In a main directory, create a file named "rmc.txt" that 
'contains the following resource strings:
'
'day=Friday
'year=2006
'holiday="Cinco de Mayo"
'
'2) Use the resgen.exe tool to generate the "rmc.resources" 
'resource file from the "rmc.txt" input file.
'
'> resgen rmc.txt
'
'Satellite Assembly:
'3) Create a subdirectory of the main directory and name the 
'subdirectory "es-ES", which is the culture name of the 
'satellite assembly.
'
'4) Create a file named "rmc.es-ES.txt" that contains the 
'following resource strings:
'
'day=Viernes
'year=2006
'holiday="Cinco de Mayo"
'
'5) Use the resgen.exe tool to generate the "rmc.es-ES.resources" 
'resource file from the "rmc.es-ES.txt" input file.
'
'> resgen rmc.es-ES.txt
'
'6) Use the al.exe tool to create a satellite assembly. If the 
'base name of the application is "rmc", the satellite assembly 
'name must be "rmc.resources.dll". Also, specify the culture, 
'which is es-ES.
'
'> al /embed:rmc.es-ES.resources /c:es-ES /out:rmc.resources.dll 
'
'7) Assume the filename for this code example is "rmc.vb". Compile 
'rmc.vb and embed the main assembly resource file, rmc.resources, in 
'the executable assembly, rmc.exe:
'
'>vbc /res:rmc.resources rmc.vb
'
'8) Execute rmc.exe, which obtains and displays the embedded 
'resource strings.
'

Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      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. The GetExecutingAssembly() method
      ' gets rmc.exe as an Assembly object.
      Dim rm As New ResourceManager("rmc", [Assembly].GetExecutingAssembly())

      ' Obtain resources using the current UI culture.
      outputBlock.Text &= "Obtain resources using the current UI culture." & vbCrLf

      ' 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")
      outputBlock.Text += String.Format(celebrate, holiday, day, year) & vbCrLf

      ' Obtain the es-ES culture.
      Dim ci As New CultureInfo("es-ES")

      ' Get the resource strings for the day, year, and holiday 
      ' using the specified culture. Use those strings to 
      ' display a message. 
      ' Obtain resources using the es-ES culture.
      outputBlock.Text &= "Obtain resources using the es-ES culture." & vbCrLf

      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-ES" (Spanish-Spain).
      '    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.
      outputBlock.Text += String.Format(celebrate, holiday, day, year) & vbCrLf

   End Sub 'Main
End Class 'Sample

'
'This code example produces the following results:
'
'>rmc
'Obtain resources using the current UI culture.
'"5th of May" will occur on Friday in 2006.
'
'Obtain resources using the es-ES culture.
'"Cinco de Mayo" will occur on Viernes in 2006.
'

// This code example demonstrates the ResourceManager() 
// constructor and ResourceManager.GetString() method.

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

/*
Perform the following steps to use this code example:

Main assembly:
1) In a main directory, create a file named "rmc.txt" that 
contains the following resource strings:

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

2) Use the resgen.exe tool to generate the "rmc.resources" 
resource file from the "rmc.txt" input file.

> resgen rmc.txt

Satellite Assembly:
3) Create a subdirectory of the main directory and name the 
subdirectory "es-ES", which is the culture name of the 
satellite assembly.

4) Create a file named "rmc.es-ES.txt" that contains the 
following resource strings:

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

5) Use the resgen.exe tool to generate the "rmc.es-ES.resources" 
resource file from the "rmc.es-ES.txt" input file.

> resgen rmc.es-ES.txt

6) Use the al.exe tool to create a satellite assembly. If the 
base name of the application is "rmc", the satellite assembly 
name must be "rmc.resources.dll". Also, specify the culture, 
which is es-ES.

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

7) Assume the filename for this code example is "rmc.cs". Compile 
rmc.cs and embed the main assembly resource file, rmc.resources, in 
the executable assembly, rmc.exe:

>csc /res:rmc.resources rmc.cs

8) Execute rmc.exe, which obtains and displays the embedded 
resource strings.
*/

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      string day;
      string year;
      string holiday;
      string celebrate = "{0} will occur on {1} in {2}.\n";

      // Create a resource manager. The GetExecutingAssembly() method
      // gets rmc.exe as an Assembly object.

      ResourceManager rm = new ResourceManager("rmc",
                               Assembly.GetExecutingAssembly());

      // Obtain resources using the current UI culture.
      outputBlock.Text += "Obtain resources using the current UI culture." + "\n";

      // 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");
      outputBlock.Text += String.Format(celebrate, holiday, day, year) + "\n";

      // Obtain the es-ES culture.
      CultureInfo ci = new CultureInfo("es-ES");

      // Get the resource strings for the day, year, and holiday 
      // using the specified culture. Use those strings to 
      // display a message. 

      // Obtain resources using the es-ES culture.
      outputBlock.Text += "Obtain resources using the es-ES culture." + "\n";

      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-ES" (Spanish-Spain).
      //    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.
      outputBlock.Text += String.Format(celebrate, holiday, day, year) + "\n";
   }
}

/*
This code example produces the following results:

>rmc
Obtain resources using the current UI culture.
"5th of May" will occur on Friday in 2006.

Obtain resources using the es-ES culture.
"Cinco de Mayo" will occur on Viernes in 2006.

*/

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Thread Safety

This type is thread safe.

Change History

Date	History	Reason
January 2011	In the Remarks section, noted that Resource Manager works with .resources files only.	Customer feedback.

Partager via