11.9 Creating and Using Satellite Assemblies

You want to create resource libraries that you can load at runtime based on the current culture of the executing thread. You also want to include images as well as strings within the resource assembly.

Technique

The first step to create a satellite assembly is to create a resource file. There are two main ways to do so, and each method depends on the design of your application. To create a satellite assembly that simply houses localized strings, create a text file containing key/value pairs on separate lines:

 myString1=This is a string. myString2=This is another string. 

To create a resource file that uses images in addition to strings, you can use the ResEditor tool. Before you can use the tool however, you must compile it. By default, the source is located in the following folder:

 C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Samples\Tutorials  \resourcesandlocalization\reseditor 

Build the application by running the supplied build.bat file. After launching the tool, add new resources by selecting the type of the resource from the Add drop-down box, giving the resource an identifying string, and clicking the Add button. The resource appears within the property grid, and you can then edit it by either entering the string value for a string object or browsing to an image file for a Bitmap object. When you are finished, save the resource file, ensuring that you choose the .resx file format from the file type drop-down box in the Save File dialog.

Once you create the necessary text or .resx files, add them to your solution by selecting Project, Add Existing Item. If you are adding text files, you have to perform one additional step. Select the text file within the Solution Explorer and change the Build Action property from Content to Embedded Resource , as shown in Figure 11.4.

Figure 11.4. When adding localized strings in a text file to a project, you have to change the Build Action to Embedded Resource to build satellite assemblies.

If you want to create satellite assemblies for different cultures, add the ISO identifier for the culture and an optional dash ( “ ) and country/region identifier in the filename. For instance, a default resource can be named MyResources.resx , but that same resource with localized content for different cultures would be named MyResources.en.resx or MyResource.en-GB.resx .

Comments

Recipe 11.2 demonstrates a technique you can use to localize the text for each control on a Windows Form using the forms designer. What you don't see, however, is what is going on underneath the virtual IDE hood. Whenever the Language property of the Windows Form changes, a new resource file with a .resx file extension is created. .resx files are XML-based files containing a group of key and value elements. These .resx files are automatically added to the project as embedded resources. When the application is built, separate resource-only assemblies, known as satellite assemblies , are created. Based on the culture and optional country/region of that resource file, the compiler places these assemblies in a subdirectory underneath your main executing assembly. During runtime, the ResourceManager class created within the InitializeComponent method searches the correct subdirectory based on the CurrentUICulture to locate the correct resource assembly.

This nice feature adds value to you as a developer, so you should use it to your advantage. The "Technique" portion of this recipe demonstrates how to manually perform the same steps the compiler uses to create satellite assemblies for localized Windows Forms data. The process itself might seem a little obscure, however, because it revolves around a tool shipped as a sample within the .NET Framework software development kit (SDK). The reason, which is clearer in Recipe 11.11, "Saving Resource Information Using the ResourceWriter Class," is that resources are simply objects and creating a tool that can embed all possible objects within a resource file would be a cumbersome task. One could argue, however, that most satellite assemblies usually only contain string and image resources, which would necessitate a built-in IDE tool, but we leave politics for the politicians and concentrate on the technique instead.

If you choose to use the ResEditor tool to create your resource files, you might have noticed that you have the option of saving the final file as a .resx or .resources file. A .resources file is the binary form of a resource file. We encourage you to refrain from initially saving your resources in this file format. Because a .resx file is a simple text file, you are free to edit any values using a simple text editor. Also, once you add the .resx file to the project, the compiler converts it to a .resources file before it creates the satellite assembly. If you choose to save your resource file in the .resources binary format, realize that to edit it, you have to use a custom tool such as ResEditor .