Retrieving Resources in Satellite Assemblies
Ideally, you should package the resources for the default or neutral assembly with the main assembly and create a separate satellite assembly for each language that your application supports. The ResourceManager class provides access to culture-specific resources at run time and controls how the application retrieves resources using the resource fallback process. For more information, see the "Resource Fallback Process" subtopic in the Packaging and Deploying Resources topic. You are encouraged to access resources through one of the constructors for the ResourceManager class. This requires resources to be either compiled into satellite assemblies, or a part of the application's main assembly.
The ResourceManager determines which resources to retrieve based upon the current thread's CultureInfo.CurrentUICulture property. For example, if an application is compiled with default English language resources and two satellite assemblies containing resources for French and German language resources, and the CurrentUICulture property is set to "de", the ResourceManager retrieves the German resources. For more information about how to set the CurrentUICulture property, see Using the CurrentUICulture Property.
The following example uses the ResourceManager.GetString method to retrieve and display a string resource.
…
Dim private rm As ResourceManager
rm = New ResourceManager("MyStrings", Me.GetType().Assembly)
Console.Writeline(rm.GetString("string1"))
…
…
private ResourceManager rm;
rm = new ResourceManager("MyStrings", this.GetType().Assembly);
Console.Writeline(rm.GetString("string1"));
…
This code retrieves and displays string1 from the file MyStrings. The actual string that gets loaded depends upon the current thread's CurrentUICulture property.
The following example uses the ResourceManager.GetObject method to retrieve and display a binary resource (such as a graphic image).
…
Dim private rm As ResourceManager
rm = New ResourceManager("MyImages", Me.GetType().Assembly)
PictureBox.Image = Ctype(rm.GetObject("MyObject"), System.Drawing.Image)
…
…
private ResourceManager rm;
rm = new ResourceManager("MyImages", this.GetType().Assembly);
PictureBox.Image = (System.Drawing.Image)rm.GetObject("MyObject");
…
This code loads the object named MyObject from the resource file, MyImages. It casts MyObject to an Image type and assigns it to the image property of PictureBox. The actual object that gets loaded depends upon the current thread's CurrentUICulture property.
The ResourceSet class stores all the resources localized for a single culture. A ResourceSet does not use the resource fallback process. Therefore, a ResourceSet is not as useful in localized applications.
Versioning Support for Satellite Assemblies
By default, when the ResourceManager retrieves requested resources, it looks for satellite assemblies with version numbers that match the version number of the main assembly. After you have deployed an application, you might want to update the main assembly or specific resource satellite assemblies. The .NET Framework provides support for versioning the main assembly and satellite assemblies.
The SatelliteContractVersionAttribute class provides versioning support for a main assembly. Specifying the SatelliteContractVersionAttribute on an application's main assembly allows you to update and re-deploy a main assembly without updating its satellite assemblies. After you update the main assembly, increment the main assembly's version number but leave the satellite contract version number as is. When the ResourceManager retrieves requested resources, it will load the satellite assembly version specified by this attribute.
Publisher policy assemblies provide support for versioning satellite assemblies. You can update and re-deploy a satellite assembly without updating the main assembly. After you update a satellite assembly, increment its version number and ship it along with a publisher policy assembly. In the publisher policy assembly, specify that your new satellite assembly is backward-compatible with its previous version. Although the ResourceManager will use the main assembly's existing satellite contract version number to retrieve requested resources, the correct updated version of the assembly will be retrieved because the assembly loader will bind to the satellite assembly version specified in the publisher policy assembly. For more information on publisher policy assemblies, see Creating a Publisher Policy File.
To enable full assembly versioning support, it is recommended that you deploy strong-named assemblies in the global assembly cache and deploy assemblies without strong names in the application directory. If you want to deploy strong-named assemblies in the application directory, you will not be able to increment a satellite assembly's version number when you update the assembly. Instead, you must perform an in-place update where you replace the existing code with the updated code and maintain the same version number. For example, if you want to update version 1.0.0.0 of a satellite assembly with the fully specified assembly name "myApp.resources, Version=1.0.0.0, Culture=de, PublicKeyToken=b03f5f11d50a3a", overwrite it with the updated myApp.resources.dll that has been compiled with the same fully specified assembly name "myApp.resources, Version=1.0.0.0, Culture=de, PublicKeyToken=b03f5f11d50a3a". Note that because the version number cannot be incremented, using in-place updates on satellite assembly files makes it difficult for an application to accurately determine the version of a satellite assembly.
For more information on assembly versioning, see Assembly Versioning and How the Runtime Locates Assemblies.
See Also
Reference
Concepts
Resources in Applications
Packaging and Deploying Resources
How the Runtime Locates Assemblies
Retrieving Resources in .Resources Files