System.Resources.ResourceManager Class

Summary

Provides convenient access to culture-specific resources at runtime.

C# Syntax:

[Serializable] public class ResourceManager

This type is safe for multithreaded operations.

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 ResourceManager.GetObject and ResourceManager.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 granularity you want. The CultureInfo 's CultureInfo.Name property is used to determine the cultureName. A resource for the neutral culture (returned by CultureInfo.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, publically 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 assistance with localization of Windows Forms dialogs, see the tool in the Microsoft .NET Framework SDK. To learn more about creating satellite assemblies, see the conceptual topic at MSDN: creatingsatelliteassemblies.

To learn more about setting up and creating resources, see the conceptual topic at MSDN: creatingusingresources.

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 ResourceManager.ReleaseAllResources method. If you want to deploy resources into ASP.NET applications, you should compile your .resources into satellite assemblies. Resources marked as private are accesible only in the assembly in which they are placed. Because a satellite assembly contains no code, resources private to it become unavailable thrugh 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.

System.Resources Namespace | CultureInfo | SatelliteContractVersionAttribute | MSDN: designingglobalapplications

System.Resources.ResourceManager Member List:

Public Constructors

ctor #2	Overloaded: .ctor(Type resourceSource) Creates a ResourceManager that looks up resources in satellite assemblies based on information from the specified Type.
ctor #3	Overloaded: .ctor(string baseName, Assembly 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.
ctor #4	Overloaded: .ctor(string baseName, Assembly assembly, Type usingResourceSet) 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.

Public Fields

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.

Public Properties

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

Public Methods

CreateFileBasedResourceManager	Returns a ResourceManager that searches a specific directory for resources instead of in the assembly manifest.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetObject	Overloaded: GetObject(string name) Returns the value of the specified Object resource.
GetObject	Overloaded: GetObject(string name, CultureInfo culture) Gets the value of the Object resource localized for the specified culture.
GetResourceSet	Gets the ResourceSet for a particular culture.
GetString	Overloaded: GetString(string name) Returns the value of the specified String resource.
GetString	Overloaded: GetString(string name, CultureInfo culture) Gets the value of the String resource localized for the specified culture.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ReleaseAllResources	Tells the ResourceManager to call ResourceSet.Close on all ResourceSet objects and release all resources.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Constructors

ctor #1

Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the ResourceManager class with default values.

Protected Fields

BaseNameField	Indicates the root name of the resource files that the ResourceManager searches for resources.
MainAssembly	Indicates the main Assembly that contains the resources.
ResourceSets	Contains a Hashtable that returns a mapping from cultures to ResourceSet objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
GetNeutralResourcesLanguage	Returns the CultureInfo for the main assembly's neutral resources by reading the value of the NeutralResourcesLanguageAttribute on a specified Assembly.
GetResourceFileName	Generates the name for the resource file for the given CultureInfo.
GetSatelliteContractVersion	Returns the Version specified by the SatelliteContractVersionAttribute in the given assembly.
InternalGetResourceSet	Provides the implementation for finding a ResourceSet.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Resources.ResourceManager

System.Resources.ResourceManager Member Details

Summary

Initializes a new instance of the ResourceManager class with default values.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

protected ResourceManager();

The current constructor is only useful for writing your own derived class of the ResourceManager.

Return to top

Summary

Creates a ResourceManager that looks up resources in satellite assemblies based on information from the specified Type.

C# Syntax:

public ResourceManager(    Type resourceSource );

resourceSource

A Type from which the ResourceManager derives all information for finding .resources files.

Exceptions

Exception Type	Condition
ArgumentNullException	The resourceSource parameter is null.

The ResourceManager infer the assembly, the base name, and a namespace for .resources files from the Type. The ResourceManager assumes you will be using satellite assemblies and want to use the default ResourceSet class. Given a type such as MyCompany.MyProduct.MyType, the ResourceManager will look for a .resources file (in the main assembly and satellite assemblies) named "MyCompany.MyProduct.MyType.[culture name.]resources" in the assembly that defines MyType.

Return to top

Summary

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.

C# Syntax:

public ResourceManager(    string baseName,    Assembly assembly );

baseName

The root name of the resources. For example, the root name for the resource file named "MyResource.en-US.resources" is "MyResource".

assembly

The main Assembly for the resources.

Exceptions

Exception Type	Condition
ArgumentNullException	The baseName or assembly parameter is null.

The individual resource files should be contained in satellite assemblies with the invariant culture's .resources file contained in the main assembly. A satellite assembly is assumed to contain resources for a single culture specified in that assembly's manifest, and are loaded as necessary.

This constructor uses the system provided ResourceSet implementation. To use a custom resource file format, you should derive from the ResourceSet class, override ResourceSet.GetDefaultReader and ResourceSet.GetDefaultWriter, and pass that type to the constructor that takes a Type as the third parameter. Using a custom ResourceSet can be useful for controlling resource caching policy or supporting your own resource file format, but is generally not necessary.

Return to top

Summary

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.

C# Syntax:

public ResourceManager(    string baseName,    Assembly assembly,    Type usingResourceSet );

baseName

The root name of the resources. For example, the root name for the resource file named "MyResource.en-US.resources" is "MyResource".

assembly

The main Assembly for the resources.

usingResourceSet

The Type of the custom ResourceSet to use. If null, the default runtime ResourceSet is used.

Exceptions

Exception Type	Condition
ArgumentException	usingResourceset is not a derived class of ResourceSet.
ArgumentNullException	The baseName or assembly parameter is null.

The individual resource files should be contained in satellite assemblies with the invariant culture's .resources file contained in the main assembly. A satellite assembly is assumed to contain resources for a single culture specified in that assembly's manifest, and are loaded as necessary.

You can specify a ResourceSet implementation to be used. If you do not need a specific ResourceSet implementation but would like to use a custom resource file format, you should derive from the ResourceSet class, override ResourceSet.GetDefaultReader and ResourceSet.GetDefaultWriter, and pass that type to this constructor.

Note The usingResourceSet parameter is used to support your own resource format, and will commonly be null. This is different from the constructor that takes a Type only.

Return to top

Summary

Indicates the root name of the resource files that the ResourceManager searches for resources.

C# Syntax:

protected string BaseNameField;

Return to top

Summary

A constant readonly value indicating the version of resource file headers that the current implementation of ResourceManager can interpret and produce.

C# Syntax:

public static readonly int HeaderVersionNumber;

Return to top

Summary

Holds the number used to identify resource files.

C# Syntax:

public static readonly int MagicNumber;

The value is set to 0xBEEFCACE. The first four bytes of the system default file format contain a 32-bit signed integer in little-endian format (see Encoding).

If the ResourceManager.MagicNumber is found, the bytes following it will be a version number for a ResourceManager header, followed by a number indicating how many bytes should be skipped to get past this header. The next number indicates the version of the ResourceManager that created the header, followed by version specific information.

The version number for the current implementation is one. The next bytes are a length-prefixed string containing the name of an IResourceReader, which can read this file.

Return to top

Summary

Indicates the main Assembly that contains the resources.

C# Syntax:

protected Assembly MainAssembly;

Return to top

Summary

Contains a Hashtable that returns a mapping from cultures to ResourceSet objects.

C# Syntax:

protected Hashtable ResourceSets;

Return to top

Summary

Gets the root name of the resource files that the ResourceManager searches for resources.

C# Syntax:

public virtual string BaseName {get;}

Return to top

Summary

Gets or sets a Boolean value indicating whether the current instance of ResourceManager allows case-insensitive resource lookups in the ResourceManager.GetString and ResourceManager.GetObject methods.

C# Syntax:

public virtual bool IgnoreCase {get; set;}

The current property indicates whether a resource with the name "Resource" is equivalent to the resource with the name "resource". If the value of the ResourceManager.IgnoreCase property is true, the two resource strings would cause the current instance of ResourceManager to return the same resource value. If the property value is false, the resource values corresponding to the two resource strings can be different.

Note For performance reasons, it is best to always specify the correct case for your resource names. ResourceManager.IgnoreCase can cause a significant workingset and performance hit.

Return to top

Summary

Gets the Type of the ResourceSet the ResourceManager uses to construct a ResourceSet object.

C# Syntax:

public virtual Type ResourceSetType {get;}

Return to top

Summary

Returns a ResourceManager that searches a specific directory for resources instead of in the assembly manifest.

C# Syntax:

public static ResourceManager CreateFileBasedResourceManager(    string baseName,    string resourceDir,    Type usingResourceSet );

baseName

The root name of the resources. For example, the root name for the resource file named "MyResource.en-US.resources" is "MyResource".

resourceDir

The name of the directory to search for the resources.

usingResourceSet

The Type of the custom ResourceSet to use. If null, the default runtime ResourceSet is used.

Return Value:

The newly created ResourceManager that searches a specific directory for resources instead of in the assembly manifest.

Exceptions

Exception Type	Condition
ArgumentException	The baseName ends in .resources.
ArgumentNullException	The baseName parameter is null.

This method returns a ResourceManager that is not dependent on any particular assembly. The returned ResourceManager can be used to load resources for an ASP.NET page or for testing a ResourceSet implementation.

You can specify a ResourceSet implementation. If you do not need a specific ResourceSet implementation, but would like to use a custom resource file format, you should derive from the ResourceSet class, override ResourceSet.GetDefaultReader and ResourceSet.GetDefaultWriter, and pass that type to this constructor.

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 ResourceManager.ReleaseAllResources method. If you want to deploy resources into ASP.NET applications, compile your .resources into satellite assemblies.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~ResourceManager();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the CultureInfo for the main assembly's neutral resources by reading the value of the NeutralResourcesLanguageAttribute on a specified Assembly.

C# Syntax:

protected static CultureInfo GetNeutralResourcesLanguage(    Assembly a );

a

The assembly for which to return a CultureInfo.

Return Value:

The culture from the NeutralResourcesLanguageAttribute, if found; otherwise, CultureInfo.InvariantCulture.

Use this method in derived classes of the ResourceManager to speed up lookups in one particular culture. For example, if this method returns "en-US" for the CultureInfo, then any U.S. English resource lookups will go straight to the main assembly and not look for the "en-US" nor "en" satellite assemblies.

Return to top

Summary

Returns the value of the specified Object resource.

C# Syntax:

public virtual object GetObject(    string name );

name

The name of the resource to get.

Return Value:

The value of the resource localized for the caller's current culture settings. If a match is not possible, null is returned. The resource value can be null.

Exceptions

Exception Type	Condition
ArgumentNullException	The name parameter is null.
MissingManifestResourceException	No usable set of resources has been found, and there are no neutral culture resources.

The returned resource is localized for the culture determined by the current cultural settings of the current Thread (this is accomplished using the culture's CultureInfo.CurrentUICulture property). If the resource has not been localized for that culture, the resource that is returned is localized for a best match (this is accomplished using the CultureInfo.Parent property). Otherwise, null is returned.

If no usable set of resources has been found, the ResourceManager falls back on the neutral culture's resources, which are expected to be included in the main assembly. If an appropriate culture resource has not been found, a MissingManifestResourceException is thrown.

Note The ResourceManager.GetObject method is thread-safe.

Return to top

Summary

Gets the value of the Object resource localized for the specified culture.

C# Syntax:

public virtual object GetObject(    string name,    CultureInfo culture );

name

The name of the resource to get.

culture

The CultureInfo object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's CultureInfo.Parent property, stopping after checking in the neutral culture.

If this value is null, the CultureInfo is obtained using the culture's CultureInfo.CurrentUICulture property.

The CultureInfo object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's CultureInfo.Parent property, stopping after checking in the neutral culture.

If this value is null, the CultureInfo is obtained using the culture's CultureInfo.CurrentUICulture property.

Return Value:

The value of the resource, localized for the specified culture. If a "best match" is not possible, null is returned.

Exceptions

Exception Type	Condition
ArgumentNullException	The name parameter is null.
MissingManifestResourceException	No usable set of resources have been found, and there are no neutral culture resources.

If the resource has not been localized for the specified culture, the resource that is returned is localized for a best match (this is accomplished using the culture's CultureInfo.CurrentUICulture property). Otherwise, null is returned.

If no usable set of resources has been found, the ResourceManager falls back on the neutral culture's resources, which are expected to be included in the main assembly. If an appropriate culture resource has not been found, a MissingManifestResourceException is thrown.

Note The ResourceManager.GetObject method is thread-safe.

Return to top

Summary

Generates the name for the resource file for the given CultureInfo.

C# Syntax:

protected virtual string GetResourceFileName(    CultureInfo culture );

culture

The CultureInfo for which a resource file name is constructed.

Return Value:

The name that can be used for a resource file for the given CultureInfo.

This method uses CultureInfo 's CultureInfo.Name property as part of the file name for all cultures other than the invariant culture. This method does not look in an assembly's manifest or touch the disk, and is used only to construct what a resource file name (suitable for passing to the ResourceReader constructor) or a manifest resource blob name should be.

A derived class can override this method to look for a different extension, such as ".ResX", or a completely different scheme for naming files.

Return to top

Summary

Gets the ResourceSet for a particular culture.

C# Syntax:

public virtual ResourceSet GetResourceSet(    CultureInfo culture,    bool createIfNotExists,    bool tryParents );

culture

The CultureInfo to look for.

createIfNotExists

If true and if the ResourceSet has not been loaded yet, load it.

tryParents

If the ResourceSet cannot be loaded, try parent CultureInfo objects to see if they exist.

Return Value:

The specified ResourceSet.

Exceptions

Exception Type	Condition
ArgumentNullException	The culture parameter is null.

The ResourceSet that is returned represents the resources localized for the specified culture. If the resources have not been localized for that culture and tryParents is true, ResourceManager.GetResourceSet falls back to a parent culture (this is accomplished using CultureInfo 's CultureInfo.Parent property), and the parent ResourceSet is returned. Otherwise, null is returned.

The parameters let you control whether the ResourceSet is created if it hasn't been loaded yet, and whether parent CultureInfo objects should be loaded as well for resource inheritance.

Note The ResourceManager.GetResourceSet method is thread-safe.

Return to top

Summary

Returns the Version specified by the SatelliteContractVersionAttribute in the given assembly.

C# Syntax:

protected static Version GetSatelliteContractVersion(    Assembly a );

a

The Assembly for which to look up the SatelliteContractVersionAttribute.

Return Value:

The satellite contract Version of the given assembly, or null if no version was found.

Exceptions

Exception Type	Condition
ArgumentException	The Version found in the assembly a is invalid.

For more information about satellite assembly versioning, see SatelliteContractVersionAttribute.

Return to top

Summary

Returns the value of the specified String resource.

C# Syntax:

public virtual string GetString(    string name );

name

The name of the resource to get.

Return Value:

The value of the resource localized for the caller's current culture settings. If a match is not possible, null is returned.

Exceptions

Exception Type	Condition
ArgumentNullException	The name parameter is null.
InvalidOperationException	The value of the specified resource is not a string.
MissingManifestResourceException	No usable set of resources has been found, and there are no neutral culture resources.

The resource that is returned is localized for the culture determined by the cultural settings of the current Thread (this is accomplished using the culture's CultureInfo.CurrentUICulture property). If the resource has not been localized for that culture, the resource that is returned is localized for a best match (this is accomplished using the CultureInfo.Parent property). Otherwise, null is returned.

If no usable set of resources has been found, the ResourceManager falls back on the neutral culture's resources, which are expected to be in the main assembly. If an appropriate culture resource has not been found, a MissingManifestResourceException is thrown.

Note The ResourceManager.GetString method is thread-safe.

Return to top

Summary

Gets the value of the String resource localized for the specified culture.

C# Syntax:

public virtual string GetString(    string name,    CultureInfo culture );

name

The name of the resource to get.

culture

The CultureInfo object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's CultureInfo.Parent property, stopping after looking in the neutral culture.

If this value is null, the CultureInfo is obtained using the culture's CultureInfo.CurrentUICulture property.

The CultureInfo object that represents the culture for which the resource is localized. Note that if the resource is not localized for this culture, the lookup will fall back using the culture's CultureInfo.Parent property, stopping after looking in the neutral culture.

If this value is null, the CultureInfo is obtained using the culture's CultureInfo.CurrentUICulture property.

Return Value:

The value of the resource localized for the specified culture. If a best match is not possible, null is returned.

Exceptions

Exception Type	Condition
ArgumentNullException	The name parameter is null.
InvalidOperationException	The value of the specified resource is not a String.
MissingManifestResourceException	No usable set of resources has been found, and there are no neutral culture resources.

If the resource has not been localized for that culture, the resource that is returned is localized for a best match (this is accomplished using the culture's CultureInfo.Parent property). Otherwise, null is returned.

If no usable set of resources has been found, the ResourceManager falls back on the neutral culture's resources, which are expected to be in the main assembly. If an appropriate culture resource has not been found, a MissingManifestResourceException is thrown.

Note The ResourceManager.GetString method is thread-safe.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Provides the implementation for finding a ResourceSet.

C# Syntax:

protected virtual ResourceSet InternalGetResourceSet(    CultureInfo culture,    bool createIfNotExists,    bool tryParents );

culture

The CultureInfo to look for.

createIfNotExists

If true and if the ResourceSet has not been loaded yet, load it.

tryParents

If the ResourceSet cannot be loaded, try parent CultureInfo objects to see if they exist.

Return Value:

The specified ResourceSet.

Exceptions

Exception Type	Condition
MissingManifestResourceException	The main assembly does not contain a .resources file and it is required to look up a resource.

Notes to inheritors: This method completes all the work necessary to find a ResourceSet, and can be recursive and reentrant. In other words, this method might load an assembly, triggering an AppDomain.AssemblyLoad event, which then calls back into the not-completely-initialized ResourceManager. To avoid taking extra locks, it is not thread safe. ResourceManager.GetResourceSet, ResourceManager.GetString, and ResourceManager.GetObject do all the necessary synchronization.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Tells the ResourceManager to call ResourceSet.Close on all ResourceSet objects and release all resources.

C# Syntax:

public virtual void ReleaseAllResources();

This method will shrink the working set in a running application. Any future resource lookups on this ResourceManager will be as extensive as the first lookup, since it will need to search and load resources again.

This can be useful in some complex threading scenarios, where creating a new ResourceManager is the appropriate behavior.

This method can also be used in situations where the .resources files opened by the current ResourceManager have to be released deterministically, without waiting for the ResourceManager to go completely out of scope and be garbage collected.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page