Shared Assemblies

A shared assembly is shared among multiple applications on a machine. It is therefore stored in a central location called the global assembly cache (GAC) and enjoys special services such as file security, shared location, and side-by-side versioning.

Assigning a Strong Name to an Assembly

An assembly is identified by its text name (usually the name of the file without the file extension), version number, and culture information. A strong name strengthens an assembly's identity by qualifying it with the software publisher's identity. The .NET Framework uses a standard cryptography technique known as digital signing to ensure the uniqueness of an assembly.

The process of digital signing involves two related pieces of binary data: a public key and a private key. The public key is stored in the assembly manifest, along with other identification information such as the name, version number, and culture of the assembly. To verify that only the legitimate owner of the public key has created the assembly, an assembly is signed using the publisher's private key. The private key is assumed to be known only to the publisher of the assembly.

You can generate public/private key pairs using the Strong Name tool ( sn.exe ), which is available in the .NET Framework SDK. For example, the following command creates a pair of public/private keys, both of which are created and stored in a file named RandNumCorpKeys.snk :

 sn k RandNumCorpKeys.snk 

Copy this strong name key file to the root directory of the solution, where you will use it for creating strong names for the assemblies. Follow these steps to learn how to create a strong named assembly:

1. Create a new Visual C# .NET Class Library project to the current solution; name it RandomNumber .

2. Delete the default Class1.cs file. Add a new Component class ( RandomNumber.cs ) to the project and add the following code to the RandomNumber class:

    //stores minValue and maxValue private int minValue=1, maxValue=100; public int MinValue {     get{        return minValue;     }     set{        minValue = value;    } } public int MaxValue {     get{         return maxValue;     }     set{         maxValue = value;     } } public int GetNext() {     Random r = new Random();     return r.Next(minValue, maxValue); } 

3. Open the AssemblyInfo.cs file. Scroll down in the file and change the AssemblyVersion and AssemblyKeyFile attributes as shown here:

    [assembly: AssemblyVersion("1.0")] [assembly: AssemblyKeyFile(@"..\..\..\RandNumCorpKeys.snk")] 

4. Build the project. A RandomNumber.dll file is generated, and a strong name is assigned to the file based on the specified key file.

In the previous example, you used Visual Studio .NET to attach a strong name to an assembly. If you want to do this manually, you can use the Assembly Linker tool ( al.exe ) with the keyfile option.

Adding an Assembly to the GAC

After you have associated a strong name with an assembly, you can place it in the GAC in several ways, including these:

• Windows Installer Microsoft Windows Installer is the preferred way of adding assemblies to the GAC. Windows Installer maintains a reference count for assemblies in the GAC and provides uninstallation support.

• Windows Explorer You can open the assembly cache folder ( c:\windows\assembly , where c:\windows is the Windows installation directory) and add an assembly through the drag-and-drop method.

• The .NET Framework Configuration tool You can also use the .NET Framework Configuration tool ( mscorcfg .msc ) to add or remove an assembly in the GAC. This tool also helps you configure assemblies and manage their runtime security policies.

• The Global Assembly Cache tool The Global Assembly Cache tool ( gacutil.exe ) is a command-line tool that is especially useful for adding and removing assemblies from the GAC via a program script or batch file. To install an assembly, you use the option /i , as shown here:

   gacutil /i RandomNumber.dll 

  To uninstall the assembly, you use the option /u , as shown here:

   gacutil /u RandomNumber.dll 

  You can also choose to uninstall from the GAC an assembly of a specific version and specific culture by specifying its version, culture, and public key, along with the name of the assembly, like so:

   gacutil /u RandomNumber,Version=1.0.0.0, Culture=neutral,PublicKeyToken=f26af4dbb33881b1 

You need to have administrative privileges on a computer to manage its GAC.

After you have added the RandomNumber.dll to the GAC using any of the methods mentioned previously, perform the following steps to create a Web application that, when executed, loads the component installed in the GAC:

1. Add a new Visual C# ASP.NET Web Application project ( RandomNumberApp ) to the solution.

2. Use the Add Reference dialog box to add a reference to RandomNumber.dll . Set the Copy Local property of the RandomNumber.dll file to false .

3. Customize the Visual Studio .NET Toolbox to add an icon for the .NET Framework component, RandomNumber.dll .

4. Drag the RandomNumber component from the toolbox and drop it on the form. Change its MaxValue property to 1000 and change its MinValue property to 500 .

5. Add a Label control ( lblResult ) and a Button control ( btnGetRandom ) to the form. Set the Button control's Text property to Get a Random Number . Then double-click the Button control to add an event handler for its Click event. Add the following code to the event handler:

    private void btnGetRandom_Click(object sender, System.EventArgs e) {     lblResult.Text = String.Format("The next random number is: {0}",        randomNumber1.GetNext()); } 

6. Set the project as the startup project and run the application. Click the button and you get a random number between 500 and 1,000 every time you click the button.

In the previous example, the RandomNumber.dll assembly is not locally copied to the bin directory of the Web application. Instead, the application loads the assembly from the GAC.

Delay Signing an Assembly

In most companies, the private key is stored securely and only a few people have access to it.

The .NET Framework supports the delay signing technique for developments in such scenarios.

With delay signing, you use only the public key to build an assembly. Associating public keys with an assembly enables you to place the assembly in the GAC and complete most of the development and testing tasks with the assembly. Later, when you are ready to package the assembly, someone who is authorized signs the assembly with the private key. The following list summarizes the various steps involved with delay signing:

1. Extract a public key from the public/private key pair To extract the public key from a file that is storing the public/private key pair, you use the Strong Name tool as follows :

    sn.exe p RandNumCorpKeys.snk RandNumCorpPublicKey.snk 

2. Delay sign an assembly using Visual Studio .NET To use delay signing in a Visual Studio .NET project, you need to modify the following two attributes of the project's AssemblyInfo.cs file and build the assembly:

    [assembly: AssemblyDelaySign(true)] [assembly: AssemblyKeyFile("RandNumCorpPublicKey.snk")] 

3. Turn off verification for an assembly in the GAC By default, the GAC verifies the strong name of each assembly. If the assembly is not signed using the private key, this verification fails. You can relax this verification for an assembly by issuing the following command:

    sn.exe Vr RandomNumber.dll 

   If you execute this command, the GAC always skips the verification for this assembly in the future.

4. Sign a delay-signed assembly with the private key When you are ready to deploy a delay-signed assembly, you need to sign it with the company's private key, like so:

    sn.exe R RandomNumber.dll RandNumCorpKeys.snk 

5. Turn on verification for an assembly in the GAC Finally, you can instruct the GAC to turn on verification for an assembly by issuing the following command:

    sn.exe Vu RandomNumber.dll 

Delay Signing Using the Assembly Linker Tool

While generating an assembly, you can also instruct the Assembly Linker tool to sign or delay sign an assembly with the given public/private key file. When you use al.exe for delay signing, you use the arguments listed in Table 14.1 with the command.

Table 14.1. Arguments Passed to al.exe for Delay Signing

Argument	Description
< sourcefiles >	You replace < sourcefiles > with the names of one or more complied modules that will be the parts of the resulting assembly.
/delay[sign][+-]	You can use either the delay argument or the delay[sign] argument for delay signing. The + option is used to delay sign the assembly by storing just the public key manifest in the assembly manifest. The option is used to fully sign an assembly by using both the public and private keys. If you do not use either + or - , the default value of is assumed.
/keyf[ile]:< filename >	You can use either keyf or keyfile to specify the key file. You replace < filename > with the name of the file that stores the key(s).
/out:< filename >	You replace < filename > with the desired name of the output assembly file.

Assume that you want to create an assembly by linking two modules, Sample1.netmodule and Sample2.netmodule . The public key file is SamplePublicKey.snk , and the desired output assembly is SignedSample.exe . You would use the al.exe command as follows:

[View full width]

 
 [View full width] 
 al.exe Sample1.netmodule,Sample2.netmodule /delaysign+ /keyfile:SamplePublicKey.snk /out:  SignedSample.exe 

An assembly signed with a strong name does not automatically assert a company's identity, such as its name. For that purpose, you can use an authenticode signature, in which case the company's identity is asserted by a third-party certification authority (such as Verisign or Thawte). You can use the File Signing tool ( signcode.exe ) to attach an authenticode signature to the assembly.

An important thing to know is the order of commands when signing an assembly using both sn.exe and signcode.exe . You must sign your assembly with the Strong Name tool ( sn.exe ) before you sign it with the File Signing tool ( signcode.exe ).

Creating a Merge Module Project

The process of packaging a component is different from the process of packaging Web applications. When you have a component such as RandomNumber that will be shared among multiple applications, you should package it as a merge module ( .msm file). A merge module includes the actual component, such as a DLL, along with any related setup logic, such as adding resources, Registry entries, custom actions, and launch conditions. Merge modules cannot be directly installedthey need to be merged with the installation program of an application that uses the shared component and packaged into a merge module.

Follow these steps to learn how to create a merge module to package a component:

1. In the Solution Explorer, right-click Solution and select Add, New Project. Select Setup and Deployment Projects from the Project Types tree, and then select Setup Wizard from the list of templates on the right. Name the project RandomNumberMergeModule .

2. Bypass the first screen of the wizard. The second screen is the Choose a Project Type screen. Select Create a Merge Module for Windows Installer as an answer to the second question Do you want to create a Redistributable Package? . Click Next.

3. The third screen of the wizard is the Choose Project Outputs to Include screen. Select Primary Output from RandomNumber and click Finish.

4. In the File System Editor, add a new folder named RandNumCorp to the Common Files Folder . Move the Primary Output from RandomNumber (Active) file in the Common Files Folder to the RandNumCorp folder.

5. Select the File System on Target Machine node and select Add Special Folder, Global Assembly Cache Folder from the context menu.

6. Select the Global Assembly Cache folder and select Add, Project Output from the context menu. The Add Project Output Group dialog box appears. Select the RandomNumber project, and select Primary Output from the list of items to be added. Then click OK.

7. Build the RandomNumberMergeModule project. Open Windows Explorer and navigate to the Release folder for the project. Notice that the RandomNumberMergeModule.msm merge module has been created.

If you later want to distribute the RandomNumber component with a Web application, you can just add the merge module created in the previous example to the Web application's setup project.