Creating Satellite Assemblies

Article
10/12/2006

The hub and spoke model described in the Packaging and Deploying Resources topic is the recommended design implementation for developing applications with resources.

The hub and spoke model requires that you place resources in specific locations, so that they can be easily located and used. If you do not compile and name resources as expected, or if you do not place them in the correct locations, the common language runtime will not be able to locate them. As a result, the runtime uses the default resource set. For more information on resource names, see CultureInfo Class or Packaging and Deploying Resources.

Compiling Satellite Assemblies

Use the Assembly Linker (Al.exe) to compile .resources files into satellite assemblies. Al.exe creates an assembly from the .resources files that you specify. By definition, satellite assemblies can only contain resources. They cannot contain any executable code.

The following Al.exe command creates a satellite assembly for the application MyApp from the file strings.de.resources.

al /t:lib /embed:strings.de.resources /culture:de /out:MyApp.resources.dll

The following Al.exe command also creates a satellite assembly for the application MyApp from the file strings.de.resources. The /template option causes the satellite assembly to inherit assembly metadata from the parent assembly MyApp.dll.

al /t:lib /embed:strings.de.resources /culture:de /out:MyApp.resources.dll
/template:MyApp.dll

The following table explains the Al.exe options used in these examples in more detail.

Option	Description
/t:lib	The /t option specifies that your satellite assembly is compiled to a library (.dll ) file. A satellite assembly cannot be executed because it does not contain code and is not an application's main assembly. Therefore, you must save satellite assemblies as DLLs.
/embed:strings.de.resources	The /embed option specifies the name of the source file to use when Al.exe compiles the assembly. Note that you can embed multiple .resources files in a satellite assembly. However, if you are following the hub and spoke model, you must compile one satellite assembly for each culture. You can, however, create separate .resources files for strings and objects.
/culture:de	The /culture option specifies the culture of the resource to compile. The runtime uses this information when it searches for the resources for a specified culture. If you omit this option, Al.exe still compiles the resource, but the runtime will not be able to find it when a user requests it.
/out:MyApp.resources.dll	The /out option specifies the name of the output file. The name must follow the naming standard baseName.resources.extension, where the baseName is the name of the main assembly, and the extension is a viable extension (such as .dll). Note that the runtime is not able to determine the culture of a satellite assembly based on its output file name. Therefore it is important to specify a culture with the /culture option described above.
/template:filename	The /template option specifies an assembly from which to inherit all assembly metadata, except the culture field. The assembly that the satellite assembly inherits from must have a strong name.

For a complete list of the options available with Al.exe, see Assembly Linker (Al.exe).

Compiling Satellite Assemblies With Strong Names

If you want to install satellite assemblies into the global assembly cache, they must have strong names. Strong-named assemblies are signed with a valid public/private key pair. For more information on strong names, see Strong-Named Assemblies.

When you are developing an application, it is unlikely that you will have access to the final public/private key pair. In order to install a satellite assembly in the global assembly cache and ensure that it works as expected, you can use a technique called delayed signing. When you delay sign an assembly, you reserve space in the file for the strong name signature at build time. The actual signing is delayed until a later date when the final public/private key pair is available.

Obtaining the Public Key

To delay sign an assembly, you must have access to the public key. You can either obtain the real public key from the organization in your company that will do the eventual signing, or create a public key using the Strong Name Tool (Sn.exe).

The following Sn.exe command creates a test public/private key pair and saves it in the file TestKeyPair.snk. The –k option specifies to Sn.exe to create a new key pair and save it in the specified file.

sn –k TestKeyPair.snk

You can extract the public key from the file containing the test key pair. The following command extracts the public key from TestKeyPair.snk and saves it in PublicKey.snk.

sn –p TestKeyPair.snk PublicKey.snk

Delay Signing an Assembly

Once you have obtained or created the public key, use the Assembly Linker (Al.exe) to compile the assembly and specify delayed signing.

The following Al.exe command creates a strong-named satellite assembly for the application MyApp from the strings.ja.resources file.

al /t:lib /embed:strings.ja.resources /culture:ja /out:MyApp.resources.dll /delay+ /keyfile:PublicKey.snk

The /delay+ option specifies to delay sign the assembly. The /keyfile: option specifies the name of the key file containing the public key to use to delay sign the assembly.

For more information on delayed signing, see Delay Signing an Assembly.

Note that strong-named assemblies contain version information that the runtime uses to determine which assembly to use to meet a binding request. For more information on this topic, see Assembly Versioning.

Re-signing an Assembly

At some later date, a delay-signed satellite assembly must be re-signed with the real key pair. You can do this using Sn.exe.

The following Sn.exe command signs MyApp.resources.dll with the real key pair stored in the file RealKeyPair.snk. The –R option specifies to Sn.exe to re-sign a previously signed or delay-signed assembly.

sn –R MyApp.resources.dll RealKeyPair.snk

Installing a Satellite Assembly in the Global Assembly Cache

In the resource fallback process, the global assembly cache is the first location the runtime searches for resources. Therefore, it is important to know how to install resources into the global assembly cache. A satellite assembly that you have compiled with a strong name is ready to install in the global assembly cache. You can install assemblies into the cache using the Global Assembly Cache Tool (Gacutil.exe).

The following Gacutil.exe command installs MyApp.resources.dll into the global assembly cache.

gacutil /i:MyApp.resources.dll

The /i option specifies to Gacutil.exe to install the specified assembly into the global assembly cache. As a result of this command, an entry is placed in the cache, which allows entries in this .resources file to be accessed. After being installed in the cache, the specified resource is available to all applications that are designed to use it.

Directory Locations for Satellite Assemblies Not Installed in the Global Assembly Cache

After you have compiled your satellite assemblies, they all have the same name. The runtime differentiates between them based upon the culture specified at compile time with Al.exe's /culture option and by each assembly's directory location. You must place your satellite assemblies in expected directory locations.

The following illustration shows a sample directory structure and location requirements for applications that you are not installing in the global assembly cache. The items with .txt and .resources file extensions will not ship with the final application. These are the intermediate resource files used to create the final satellite resource assemblies. In this example, you could substitute .resx files for the .txt files. The .resx files are the only type of intermediate resource file that can contain objects.

Satellite assembly directory

Note If your application includes resources for subcultures, place each subculture in its own directory. Do not place subcultures in subdirectories of their main culture's directory.

Share via