Embedded and Linked Resources

.NET allows arbitrary resources to be bundled within the assembly. Such resources might include image or icon files, as well as text files containing error or other messagesbut ultimately any file can be used as a resource. Assemblies can either directly embed these resources or provide a link to external resources.

Embedding a resource takes a copy of the named file and physically places it in the assembly file. Once the assembly has been built, the external file is no longer needed. At runtime, a request to access the file will be satisfied by the copy of the file included in the assembly.

As you have probably guessed, linking a resource simply embeds the file name of the resource as part of the assembly. This approach makes the file become an integral part of the assembly, and the file must subsequently be distributed as part of the assembly.

A number of reasons exist for favoring embedding over linking or linking over embedding. In some cases, linking to the original file allows you to modify the external file without rebuilding the entire assembly (but see the discussion later in this chapter on strong names and public assemblies for information on situations in which this technique does not work). Embedding a resource simplifies the deployment of an assembly, as fewer files make up the assembly; on the other hand, embedding the same resource in a number of files increases disk usage.

Example: A .NET Assembly with Embedded Resources

To demonstrate these concepts, let's extend the example assembly to use an external resource. Instead of hard-coding the AboutBox string as was done in version 1, let's use a message.txt file to hold the string.

The example must be modified in several ways to work with an embedded or linked file:

• Create the resource file message.txt for this example.

• Modify the makefile to embed or link the resource.

• Modify the code to open the linked resource and read its contents.

The complete code for this version of the assembly is found in the AboutBoxEmbed directory.

The message.txt file consists of single line:

 Embedded Application 

If all goes according to plan, the modified code will display this text in a dialog.

The C# compiler used to generate the assembly supports two relevant command-line options: /resource: to embed a resource and /linkresource: to link to an external resource. This version of the assembly demonstrates embedding a resource, so the makefile uses the /resource: option.

The complete command (from the makefile ) for building the assembly follows :

 csc /t:library /resource:message.txt AboutBox.cs \      ..\AboutBoxBase.cs 

The C# code will reference the embedded resource, so it will take advantage of the System.Reflection.Assembly.GetManifestResource-Stream() function. This function returns a System.IO.Stream object, which is wrapped in a System.IO.StreamReader object to read the contents as a simple string. Listing 5.2 shows the modified code.

Listing 5.2 AboutBox : Version 2

 using System.Reflection; using System.IO; namespace AboutBoxSample {     public class AboutBox : AboutBoxBase     {         public override string GetAboutText()         {             // Get the about box text from the             // embedded text file.             Assembly ass = Assembly.GetExecutingAssembly();             Stream stream =               ass.GetManifestResourceStream("message.txt");             StreamReader reader = new StreamReader(stream);             return reader.ReadToEnd();         }     } } 

You build and run this version in the same way as version 1 of the assembly. Note the text in the dialog matches that in the message.txt file (Figure 5.3).

Figure 5.3. Second version of UseAboutBox.exe in action

Embedding the resource in the assembly takes a copy of the message.txt file rather than referencing the copy on disk. If you rename or remove the message.txt file, the application will still run correctly. Changing the text in the file has no effect on the text in the application.

In this scenario, the file message.txt is technically not part of the assembly. Rather, the contents of message.txt are copied into the assembly and can be referenced by the assembly, but the file itself is not part of the assembly. This relationship is shown in Figure 5.4, where the module and the contents of the message.txt file both appear inside the single assembly file that holds the assembly manifest.

Figure 5.4. Construction of assembly with embedded resource

Example: A .NET Assembly with Linked Resources

To link to a resource instead of embedding it, you simply modify the C# command line in the makefile to use the /linkresource: option. The new makefile can be found with this chapter's samples, but the new command line appears here:

 csc /t:library /linkresource:message.txt AboutBox.cs \      ..\AboutBoxBase.cs 

The message.txt file now has the following text:

 Linked Application 

The C# source file remains unchanged. Again, you can build and test the new example, and confirm that the AboutBox message matches that expected from the new message.txt .

To prove that .NET has truly linked the resource (rather than embedded it), let's attempt to rename or remove the message.txt file. In this case, the application should not run. AssemblyBuilder.GetManifestResourceStream() will return null , causing the application to fail. Similarly, if you attempt to copy only the assembly DLL to a new directory, without also copying all referenced modules and files, the assembly should fail to work. Figure 5.5 shows the result of executing the program with the message.txt file removed.

Figure 5.5. Result of executing the assembly program without the message file

If you change the text in the file, the application as it stands will continue to run and will display the new text. However, as discussed later in this chapter, you may need to sign the assembly so that it can be effectively deployed for use. Once the assembly is signed, you cannot modify the text file, as .NET will detect the tampering.

When you link to external resources, these resources become full-fledged members of the assembly, and the assembly manifest refers to the file by name. Figure 5.6 shows this relationship. Here the assembly manifest remains in the same file as the module, but the assembly manifest also refers to the message.txt file, as shown by the solid line. The module contains an indirect reference to message.txt via a call to GetManifestResourceStream() , as shown by the dashed line.

Figure 5.6. Construction of assembly with linked resource