Creating Satellite Assemblies

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.

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

The global assembly cache is the first location the runtime searches for resources in the resource fallback process. For more information, see the "Resource Fallback Process" subtopic in the Packaging and Deploying Resources topic. 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

See Also

Reference

Al.exe (Assembly Linker)

Sn.exe (Strong Name Tool)

Gacutil.exe (Global Assembly Cache Tool)

Concepts

Packaging and Deploying Resources

Delay Signing an Assembly

Resources in Applications