Adding Assemblies to a Project by Using the Visual Studio IDE

If you’re using the Visual Studio IDE to build your project, you’ll have to add any assemblies that you want to reference to your project. To do so, open Solution Explorer, right-click the project you want to add a reference to, and then select the Add Reference menu item. This causes the Reference Manager dialog box, shown in Figure 2-2, to appear.

FIGURE 2-2The Reference Manager dialog box in Visual Studio.

To have your project reference an assembly, select the desired assembly from the list. If the assem- bly you want isn’t in the list, click the Browse button to navigate to the desired assembly (file con- taining a manifest) to add the assembly reference. The Solution option allows the current project to reference an assembly that is created by another project in the same solution. The COM option in the Reference Manager dialog box allows an unmanaged COM server to be accessed from within man- aged source code via a managed proxy class automatically generated by Visual Studio. The Browse option allows you to select an assembly that you recently added to another project.

To make your own assemblies appear in the Reference Manager’s dialog box, follow the instruc- tions at http://msdn.microsoft.com/en-us/library/wkze6zky(v=vs.110).aspx.

Using the Assembly Linker

Instead of using the C# compiler, you might want to create assemblies by using the Assembly Linker utility, AL.exe. The Assembly Linker is useful if you want to create an assembly consisting of modules built from different compilers (if your compiler doesn’t support the equivalent of C#’s /addmodule switch) or perhaps if you just don’t know your assembly packaging requirements at build time. You can also use AL.exe to build resource-only assemblies, called satellite assemblies, which are typically used for localization purposes. I’ll talk about satellite assemblies later in the chapter.

The AL.exe utility can produce an EXE or a DLL PE file that contains only a manifest describing the types in other modules. To understand how AL.exe works, let’s change the way the MultiFileLibrary.dll assembly is built.

csc /t:module RUT.cs csc /t:module FUT.cs

al /out: MultiFileLibrary.dll /t:library FUT.netmodule RUT.netmodule

Figure 2-3 shows the files that result from executing these statements.

FIGURE 2-3A multifile assembly consisting of three managed modules, one with a manifest.

In this example, two separate modules, RUT.netmodule and FUT.netmodule, are created. Neither module is an assembly because they don’t contain manifest metadata tables. Then a third file is pro- duced: MultiFileLibrary.dll, which is a small DLL PE file (because of the /t[arget]:library switch) that contains no IL code but has manifest metadata tables indicating that RUT.netmodule and FUT.net- module are part of the assembly. The resulting assembly consists of three files: MultiFileLibrary.dll,

RUT.netmodule, and FUT.netmodule. The Assembly Linker has no way to combine multiple files into a single file.

The AL.exe utility can also produce CUI, GUI, and Windows Store app PE files by using the

/t[arget]:exe, /t[arget]:winexe, or /t[arget]:appcontainerexe command-line switches. But this is very unusual because it would mean that you’d have an EXE PE file with just enough IL code in it to call a method in another module. You can specify which method in a module should be used as an entry point by adding the /main command-line switch when invoking AL.exe. The following is an example of how to call the Assembly Linker, AL.exe, by using the /main command-line switch.

csc /t:module /r:MultiFileLibrary.dll Program.cs

al /out:Program.exe /t:exe /main:Program.Main Program.netmodule

Here the first line builds the Program.cs file into a Program.netmodule file. The second line produces a small Program.exe PE file that contains the manifest metadata tables. In addition, there is a small global function named EntryPoint that is emitted by AL.exe because of the /main:Program.Main command-line switch. This function, EntryPoint, contains the following IL code.

.method privatescope static void EntryPoint$PST06000001() cil managed

{

.entrypoint

// Code size 8 (0x8)

.maxstack 8 IL_0000: tail.

IL_0002: call void [.module 'Program.netmodule']Program::Main() IL_0007: ret

} // end of method 'Global Functions':: EntryPoint

As you can see, this code simply calls the Main method contained in the Program type defined in the Program.netmodule file. The /main switch in AL.exe isn’t that useful because it’s unlikely that

you’d ever create an assembly for an application that didn’t have its entry point in the PE file that con- tains the manifest metadata tables. I mention the switch here only to make you aware of its existence.

With the code that accompanies this book, I have created a Ch02-3-BuildMultiFileLibrary.bat file that encapsulates all the steps required to build a multifile assembly. The Ch02-4-AppUsingMulti- FileLibrary project in Visual Studio invokes this batch file as a prebuild command-line step. You can examine this project to see how to integrate building and referencing a multifile assembly from within Visual Studio.

Adding Resource Files to an Assembly

When using AL.exe to create an assembly, you can add a file as a resource to the assembly by using the /embed[resource] switch. This switch takes a file (any file) and embeds the file’s contents into the resulting PE file. The manifest’s ManifestResourceDef table is updated to reflect the existence of the resources.

AL.exe also supports a /link[resource] switch, which also takes a file containing resources. However, the /link[resource] switch updates the manifest’s ManifestResourceDef and FileDef tables, indicating that the resource exists and identifying which of the assembly’s files contains it. The resource file is not embedded into the assembly PE file; it remains separate and must be packaged and deployed with the other assembly files.

Like AL.exe, CSC.exe also allows you to combine resources into an assembly produced by the C# compiler. The C# compiler’s /resource switch embeds the specified resource file into the resulting assembly PE file, updating the ManifestResourceDef table. The compiler’s /linkresource switch adds an entry to the ManifestResourceDef and the FileDef manifest tables to refer to a stand-alone resource file.

One last note about resources: it’s possible to embed standard Win32 resources into an assembly.

You can do this easily by specifying the path of a .res file with the /win32res switch when using either AL.exe or CSC.exe. In addition, you can quickly and easily embed a standard Win32 icon re- source into an assembly file by specifying the path of the .ico file with the /win32icon switch when using either AL.exe or CSC.exe. Within Visual Studio, you can add resource files to your assembly by displaying your project’s properties and then clicking the Application tab. The typical reason an icon is embedded is so that Windows Explorer can show an icon for a managed executable file.

Date: 2016-03-03; view: 707