Manually Compiling Resources

It's possible to generate the satellite assemblies manually from the source .resx files without rebuilding the entire project in Visual Studio. You will have to use the Windows command line (cmd.exe), and you will need access to the main assembly's EXE or DLL file. It's not for the faint of heart; and a single mistyped character could cost the American taxpayers millions.

Figure 18-1 summarized the steps needed to move a .resx file into a satellite assembly. The "generate" and "compile" steps can be done using two command-line utilities: resgen.exe and al.exe. Doesn't that sound like great fun?

As with other .NET command-line tools, these tools need the command-line environment to be set up just so, or they will have a snit and refuse to run. To ensure you have the correct environment, you need to open the special .NET version of the command line. The .NET SDK was installed when you installed the Framework, so you should be able to find a Start-menu entry for it at Start [All] Programs Microsoft .NET Framework SDK v2.0 SDK Command Prompt. Alternatively, you can open a standard command line and run the SDK\v2.0\bin\sdkvars.bat script found in the Visual Studio installation directory.

Resource File Generation

Once you have a .resx file available, either by creating it manually or by using the Windows [Forms] Resource Localization Editor, you generate a .resources file using resgen.exe, the Resource Generator command-line utility. It accepts an input and an output filename as its arguments.

resgen.exe Form1.ja.resx Form1.ja.resources 

If you omit the output filename, resgen will simply replace the .resx extension with .resources.

If you have multiple foreign-language assemblies (for multiple forms, for instance), generate resource files for all of them. Then you will be ready to compile the satellite assembly.

Compiling Satellite Assemblies

The Assembly Linker program al.exe is used by .NET to compile all of your .NET applications to their file assembly files. We'll use this same program to generate the satellite assemblies. Its command-line arguments were designed by a secret society, so getting them just right will take some work. Let's look at the command first, and then I'll explain it.

[View full width]
al.exe /target:lib /embed:Form1.ja.resources,ForeignNames.Form1.ja.resources /culture:ja  /out:ForeignNames.resources.dll /template:bin\Release\ForeignNames.exe 

These lines should be entered as one long line. I had to wrap them in the book because the publisher didn't want to do one of those fold-out pages that you see in some children's books. They also didn't like my interactive "pop-up" Visual Studio environment idea either. Something about keeping the book below $100 per copy.

The options provided to al.exe work all of the magic.

• /target:lib. The "lib" part says, "Output a DLL-style file."

• /embed. This option indicates which source files you want to include in the output assembly. The first comma-delimited part indicates source filename. The second part indicates the name by which this resource will be known in the application. The name must be in the format "basename.cultureName.resources," where basename is the application name (for application-wide resources) or the class name (qualified with its namespace) for a specific class, like Form1. Because my application and its default top-level namespace are both "ForeignNames," I've included that in the name component. You can add as many /embed options as you have resource files to include.

• /culture. Although you will eventually put the satellite assembly in a folder named for the target culture, Visual Basic doesn't trust you. Instead, it wants a record of the culture embedded in the assembly itself. You do that through this command-line option.

• /out. This option specifies the output name of the satellite file. You really need to use the name "application.resources.dll" for the file, where application is the same as your application's name before the ".exe" part. If you don't do this, it won't work. Well, you could still get it to work by adjusting the application's app.config file, but that file is just plain scary, so you don't want to go there.

• /template. This is the option that says, "I'm making a satellite assembly, and the related primary assembly is x."

To use the satellite assembly, locate the directory that contains the main EXE assembly. Create a new subdirectory right there, giving it the name of the language or language-culture key used to create the assembly ("ja" in my case; "ja-JP" would have been an option if I created the assembly using "Japanese (Japan)"). Then put the new satellite assembly in that subdirectory.