How to install an assembly in the .NET Framework global assembly cache (910355)


The information in this article applies to:

  • Microsoft .NET Framework 2.0 Software Development Kit English (United States)
  • Microsoft Visual Studio 2005 Team System Architect Edition
  • Microsoft Visual Studio 2005 Team System Developer Edition
  • Microsoft Visual Studio 2005 Team System Test Edition
  • Microsoft Visual Studio 2005 Team System Team Foundation:
  • Microsoft Visual Studio 2005 Standard Edition
  • Microsoft Visual Studio 2005 Professional Edition
  • Microsoft Visual Studio 2005 Express Edition
  • Microsoft Visual Basic 2005
  • Microsoft Visual C# 2005, Express Edition
For a Microsoft Visual Basic .NET version of this article, see 315682.
For a Microsoft Visual C++ 2005 and Visual C++ .NET version of this article, see 815807.
For a Microsoft Visual C# .NET version of this article, see 815808.

SUMMARY

This article describes how to install an assembly .dll file in the Microsoft .NET Framework global assembly cache. To do this, you can use the Microsoft .NET Framework Software Development Kit (SDK) Global Assembly Cache tool. An assembly must have a strong name to be installed in the global assembly cache. This article describes how to create an assembly that has a strong name by using Microsoft Visual Studio 2005. Additionally, this article describes how to verify that the assembly is installed in the global assembly cache. To accomplish this task, you must have Administrator rights to the computer where the shared assembly is installed. Additionally, you must install the .NET Framework SDK.

INTRODUCTION

This step-by-step article describes how to create an assembly that has a strong name by using Visual Studio 2005. Additionally, this article describes how to install an assembly .dll file in the .NET Framework global assembly cache. To do this, you can use the .NET Framework SDK Global Assembly Cache tool. You can also use the Global Assembly Cache tool to verify that the assembly is installed in the global assembly cache.

MORE INFORMATION

The global assembly cache

The .NET Framework global assembly cache is a code cache. The global assembly cache is automatically installed on each computer that has the .NET Framework common language runtime installed. Any application that is installed on the computer can access the global assembly cache. The global assembly cache stores assemblies that are specifically designated to be shared by several applications on the computer. Component assemblies are typically stored in the C:\WINNT\Assembly folder.

Note Only install an assembly in the global assembly cache when you must share the assembly. Unless sharing an assembly is explicitly required, we recommend that you keep assembly dependencies private and that you locate the assembly in the application directory. Additionally, you do not have to install an assembly in the global assembly cache to make the assembly available to Microsoft Component Object Model (COM) interop or to unmanaged code.

An assembly

An assembly is a fundamental part of programming with the .NET Framework. An assembly is a reusable, self-describing building block of a .NET Framework common language runtime application.

An assembly contains one or more code components that the common language runtime executes. All types and all resources in the same assembly form an individual version of the unit. The assembly manifest describes the version dependencies that you specify for any dependent assemblies. By using an assembly, you can specify version rules between different software components, and you can have those rules enforced at run time. An assembly supports side-by-side execution. This enables multiple versions to run at the same time.

Strong-name signing

An assembly must have a strong name to be installed in the global assembly cache. A strong name is a globally unique identity that cannot be spoofed by someone else. By using a strong name, you prevent components that have the same name from conflicting with each other or from being used incorrectly by a calling application. Assembly signing associates a strong name together with an assembly. Assembly signing is also named strong-name signing. A strong name consists of the following information:
  • The simple text name of the assembly
  • The version number of the assembly
  • The culture information about the assembly, if this information is provided
  • A public key and private key pair
This information is stored in a key file. The key file is either a Personal Information Exchange (.pfx) file or a certificate from the current user's Microsoft Windows certificate store.

You can sign an assembly by using the options on the Signing tab of the Project Designer in Visual Studio 2005. In Visual Studio 2005, the key file must be stored in the project folder on the local computer. Visual Studio 2005 supports only the following file formats:
  • Personal Information Exchange (.pfx) files
  • Strong name key (.snk) files

Requirements

You must meet the following requirements before you install an assembly in the global assembly cache:
  • You must have Administrator rights to the computer where the shared assembly is installed.
  • You must install the .NET Framework SDK.
This article assumes that you are familiar with the following topics:
  • General familiarity with shared assemblies in Microsoft .NET
  • General familiarity with the use of tools at a command prompt

How to install an assembly in the global assembly cache

This method is based on how to create an assembly by using Visual Studio 2005. To create an assembly that can be shared by multiple applications, the shared assembly must have a strong name. Additionally, the shared assembly must be deployed in the global assembly cache.

To create a small Microsoft Visual C# assembly that has a strong name and to install the compiled .dll file in the global assembly cache, follow these steps:
  1. Create a new Visual C# Class Library project that is named GACDemo. To do this, follow these steps:
    1. Start Visual Studio 2005.
    2. On the File menu, click New Project.
    3. In the Templates list, click Class Library.
    4. In the Name box, type GACDemo, and then click OK.
    5. To save the project, press CTRL+SHIFT+S.
    6. In the Location box, type C:\DemoProjects.
    7. Click to clear the Create directory for solution check box, and then click Save.
  2. Generate a strong name, and then associate the strong name key file together with the assembly. To do this, follow these steps:
    1. On the Project menu, click GACDemo Properties.
    2. On the Signing tab, click to select the Sign the assembly check box.
    3. Under Choose a strong name key file, click <New>.
    4. In the Create Strong Name Key dialog box, click to select the Protect my key file with a password check box.
    5. In the Key file name box, type GACDemo.
    6. In the Enter password box, type the password that you want to use.
    7. In the Confirm password box, type the same password, and then click OK.

      Note We recommend that you always use a password when you create a key file. A new key file that is protected by a password is always created in the .pfx file format.
    8. To compile the project, press CTRL+SHIFT+B.

      Note No additional code is required to install a .dll file in the global assembly cache.
  3. Install the .dll file that you created in step 2 in the global assembly cache by using the Global Assembly Cache tool. To do this, follow these steps:
    1. Click Start, click Run, type cmd, and then click OK.
    2. To change the current working directory to the directory where the .NET Framework SDK is installed, use one of the following commands:
      • If the .NET Framework version 2.0 SDK is installed, type the following command, and then press ENTER:

        cd "%ProgramFiles%\Microsoft Visual Studio 8\SDK\v2.0\Bin"

      • If the .NET Framework version 1.1 SDK is installed, type the following command, and then press ENTER:

        cd "%ProgramFiles%\Microsoft.NET\SDK\v1.1\Bin"

    3. At a command prompt, type the following command, and then press ENTER:

      gacutil -I "C:\DemoProjects\GACDemo\bin\Release\GACDemo.dll"

How to verify that the assembly is installed in the global assembly cache

You can use the Global Assembly Cache tool to verify that the assembly is installed in the global assembly cache. To do this, follow these steps:
  1. Click Start, click Run, type cmd, and then click OK.
  2. To change the current working directory to the directory where the .NET Framework SDK is installed, use one of the following commands:
    • If the .NET Framework 2.0 SDK is installed, type the following command, and then press ENTER:

      cd "%ProgramFiles%\Microsoft Visual Studio 8\SDK\v2.0\\Bin"

    • If the .NET Framework 1.1 SDK is installed, type the following command, and then press ENTER:

      cd "%ProgramFiles%\Microsoft.NET\SDK\v1.1\Bin"

  3. To display the installation information about the GACDemo assembly, use the Global Assembly Cache tool. To do this, type the following command at a command prompt, and then press ENTER:

    gacutil -l GACDemo

    Note The installation information about the GACDemo assembly is displayed.

REFERENCES

For more information about how to create an assembly that has a strong name in the .NET Framework SDK, click the following article number to view the article in the Microsoft Knowledge Base:

302340 How to create an assembly with a strong name in .NET Framework SDK

For more information about the global assembly cache, visit the following Microsoft Developer Network (MSDN) Web sites:

Assemblies overview
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconAssembliesOverview.asp

Creating assemblies
http://msdn2.microsoft.com/en-us/library/b0b8dk77(VS.80).aspx

Programming with assemblies
http://msdn2.microsoft.com/en-us/library/8wxf689z(VS.80).aspx

Working with assemblies and the global assembly cache
http://msdn2.microsoft.com/en-us/library/6axd4fx6(VS.80).aspx

How to install an assembly into the global assembly cache
http://msdn2.microsoft.com/en-us/library/dkkx7f79(VS.80).aspx

Global assembly cache
http://msdn.microsoft.com/library/en-us/cpguide/html/cpconglobalassemblycache.asp

Global Assembly Cache tool (Gacutil.exe)
http://msdn.microsoft.com/library/en-us/cptools/html/cpgrfglobalassemblycacheutilitygacutilexe.asp

Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbStepByStep kbSample kbADO kbvs2005applies kbHOWTOmaster kbhowto kbCodeSign kbCommandLine kbNameSpace KB910355 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.