How to load an assembly at runtime that is located in a folder that is not the bin folder of the application (837908)


The information in this article applies to:

  • Microsoft Visual Basic 2005
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)
  • Microsoft Visual C# 2005, Express Edition
  • Microsoft Visual C# .NET (2003)
  • Microsoft Visual C# .NET (2002)

SUMMARY

You do not have to put an assembly that an application must use at runtime in the bin folder of the application. You can put the assembly in any folder on the system, and then you can refer to the assembly at runtime.

INTRODUCTION

This step-by-step article describes three methods that you can use to refer to the assemblies that are located in folders that are not the bin folder of the application.

Requirements

This article assumes that you are familiar with the following topics:
  • General familiarity with Microsoft Visual Basic .NET or Microsoft Visual Basic 2005 or with Microsoft Visual C# .NET or Microsoft Visual C# 2005
  • General familiarity with assemblies in Visual Basic .NET or Visual Basic 2005 and in Visual C# .NET or Microsoft Visual C# 2005
  • General familiarity with .config files in Visual Basic .NET or Visual Basic 2005 and in Visual C# .NET or Microsoft Visual C# 2005
The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:
  • The Microsoft .NET Framework
  • Microsoft Visual Studio .NET or Microsoft Visual Studio 2005

Method 1: Install the assembly in the global assembly cache (GAC)

The GAC is a computer-wide code cache where the common language runtime is installed. The GAC stores assemblies that you specifically designate to be shared by several applications.

Note You can only install strong-named assemblies in the GAC.

To install an assembly in the GAC, follow these steps:
  1. Start Visual Studio .NET or Visual Studio 2005.
  2. On the File menu, point to New, and then click Project.

    The New Project dialog box appears.
  3. Under Project Types, click Visual Basic .NET, or click Visual C# .NET.

    Note In Visual Studio 2005, click Visual Basic or click Visual C#.
  4. Under Templates, click Class Library.
  5. In the Name box, type MyAssembly1. In the Location box, type C:\Myassemblies.

    By default, the Class1.vb file is created by Visual Basic .NET or Visual Basic 2005. By default, the Class1.cs file is created by Visual C# .NET or Visual C# 2005.
  6. Add the following code to the Class1 class of the Class1.vb file or of the Class1.cs file.

    Visual Basic .NET or Visual Basic 2005 code
       Public Function HelloWorld() As String
      Return "From Class Library "
   End Function
    Visual C# .NET or Visual C# 2005 code
    public string HelloWorld()
{
	return "From Class Library";
}
  7. On the File menu, click Save All to save the solution.
  8. Install the MyAssembly1 assembly in the GAC.

    For more information about how to do this in Visual Basic .NET, click the following article number to view the article in the Microsoft Knowledge Base:

    315682 How to install an assembly in the global assembly cache in Visual Basic. NET

    For more information bout how to do this in Visual C# .NET, click the following article number to view the article in the Microsoft Knowledge Base:

    815808 How to install an assembly into the global assembly cache in Visual C# .NET

  9. Create a new client application. To do this, follow these steps:
    1. In Visual Studio .NET or Visual Studio 2005, create a new Visual Basic .NET or Visual Basic 2005 Windows application or a new Visual C# .NET or Visual C# 2005 Windows application that is named TestClient1.

      By default, the Form1.vb file is created by Visual Basic .NET or Visual Basic 2005. By default, the Form1.cs file is created by Visual C# .NET or Visual C# 2005.
    2. In Solution Explorer, right-click Add Reference.

      The Add Reference dialog box appears.
    3. Click Browse, locate C:\MyAssembly, click the MyAssembly1 assembly, and then click Open.

      Note In this step, C:\MyAssembly is a placeholder for the actual location of the MyAssembly1 assembly.
    4. Add the following code to the Form1_Load event of the Form1.vb file or of the Form1.cs file as follows:

      Visual Basic .NET or Visual Basic 2005 code
      Dim obj1 As New MyAssembly1.Class1()
MessageBox.Show(obj1.HelloWorld())
      Visual C# .NET or Visual C# 2005 code
      MyAssembly1.Class1 obj1=new MyAssembly1.Class1();
MessageBox.Show(obj1.HelloWorld());
    5. On the Debug menu, click Start to build and to run the application.

Method 2: Use an application configuration (.config) file with the <codeBase> tags

A .config file contains the following settings:
  • Settings that are specific to an application
  • Settings that the common language runtime reads, such as the assembly binding policy settings and the remoting objects settings
  • Settings that the application reads
The <codeBase> tags specify where the common language runtime can find an assembly. The common language runtime applies the settings of the <codeBase> tags from the .config file. The settings of the <codeBase> tags determine the version and the location of the assembly.

To use a .config file with the <codeBase> tags to refer to the assemblies, follow these steps:
  1. Create a new Class Library project that is named MyAssembly2 by following steps 1 through 6 of the "Method 1: Install the assembly in the global assembly cache (GAC)" section.
  2. Make the assembly strong-named.

    For additional information about how to do this, click either of the article numbers that are mentioned in step 8 of the "Method 1: Install the assembly in the global assembly cache (GAC)" section.
  3. Create a new client application. To do this, follow these steps:
    1. In Visual Studio .NET or Visual Studio 2005, create a new Visual Basic .NET or Visual Basic 2005 Windows application or a new Visual C# .NET or Visual C# 2005 Windows application that is named TestClient2.

      By default, the Form1.vb file is created by Visual Basic .NET or Visual Basic 2005. By default, the Form1.cs file is created by Visual C# .NET or Visual C# 2005.
    2. In Solution Explorer, right-click Add reference.

      The Add Reference dialog box appears.
    3. Click Browse, click the MyAssembly2 assembly, and then click Open.
    4. Under References, right-click MyAssembly2, and then click Properties.

      The Properties window appears.
    5. In the Properties window, set the Copy Local property of the assembly to False.
    6. Add the following code to the Form1_Load event of the Form1.vb file or of the Form1.cs file as follows:

      Visual Basic .NET or Visual Basic 2005 code
      Dim obj2 As New MyAssembly2.Class1()
MessageBox.Show(obj2.HelloWorld())
      Visual C# .NET or Visual C# 2005 code
      MyAssembly2.Class1 obj2=new MyAssembly2.Class1();
MessageBox.Show(obj2.HelloWorld());
    7. On the Build menu, click Build Solution.
  4. Find the publicKeyToken attribute number of the assembly that you created. To do this, follow these steps:
    1. At the Visual Studio .NET or Visual Studio 2005 command prompt, locate the following folder:

      C:\MyAssemblies\MyAssembly2\bin\debug

      Note To find the publicKeyToken attribute number, locate the folder that contains your compiled library assembly. Typically, this is the bin folder in your project folder that is mentioned previously in this step.
    2. Type the following command:

      SN -T MyAssembly2.dll

      Note You must use a capital letter "T" to obtain the correct public key.

      The command returns a hexadecimal value that represents the publicKeyToken attribute number of the assembly.
  5. To find the version number of the assembly, follow these steps:
    1. In Microsoft Windows Explorer, locate the following folder:

      C:\Myassemblies\MyAssembly2\bin\debug
    2. Right-click the MyAssembly2.dll file, and then click Properties.

      The Properties window appears.
    3. In the Properties window, click the Version tab.

      Note The assembly version is specified in the Value section.
  6. Use the publicKeyToken attribute number and the version number to identify the correct assembly.

    Note You must provide the publicKeyToken attribute number, the version number, and the path of the MyAssembly2.dll file that uses the <codeBase> tags to refer to the MyAssembly2.dll file at runtime.
  7. Add a .config file to the project. To do this, follow these steps:
    1. On the Project menu, click Add New Item.
    2. In the Add New Item dialog box, click Application configuration file under Templates.
    3. Make sure that the file name is App.config, and then click Open.
    4. Add the following code to the file:
      <configuration>
   <runtime>
      <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <dependentAssembly>
            <assemblyIdentity name="MyAssembly2"  culture="neutral" publicKeyToken="307041694a995978"/>
            <codeBase version="1.0.1524.23149" href="FILE://C:/Myassemblies/MyAssembly2.dll"/>
         </dependentAssembly>
      </assemblyBinding>
   </runtime>
</configuration>
      Note The TestClient2.exe.config file is located in the Debug folder or in the Release folder. Both of these folders are located in the bin folder. The solution configuration mode that you select determines the location of the TestClient2.exe.config file.
  8. Make the following changes in the <assemblyIdentity> tags:
    1. Change the name attribute to the name of your library assembly.
    2. Change the publicKeyToken attribute to the public key that you determined in step 4 of this section.
  9. Make the following changes in the <codeBase> tags:
    1. Change the version attribute to the version number of the assembly that you determined in step 5 of this section.
    2. Change the href attribute to the path where the DLL is located.
  10. On the Debug menu, click Start to build the project, and then run the application.

Method 3: Use the AssemblyResolve event

The AssemblyResolve event fires whenever the common language runtime tries to bind to an assembly and fails. You can use the AddHandler method to add an event handler to the application that returns the correct assembly whenever the AssemblyResolve event fires.

The AssemblyResolve event handler must return an [Assembly] object, and the common language runtime must bind to this object. Typically, you can use the Assembly.LoadFrom method to load the assembly and then to return the object. To do this, follow these steps:
  1. Create a new Class Library project that is named MyAssembly3 by following steps 1 through 7 of the "Method 1: Install the assembly in the global assembly cache (GAC)" section.
  2. Create a new client application. To do this, follow these steps:
    1. In Visual Studio .NET or Visual Studio 2005, create a new Visual Basic .NET or Visual Basic 2005 Windows application or create a new Visual C# .NET or Visual C# 2005 Windows application that is named TestClient3.

      By default, the Form1.vb file is created by Visual Basic .NET or Visual Basic 2005. By default, the Form1.cs file is created by Visual C# .NET or Visual C# 2005.
    2. Add a Button control to the Form1.vb file or to the Form1.cs file.
    3. Double-click the Button1 control, and then add the following code to the Button1_Click event:

      Visual Basic .NET or Visual Basic 2005 code
      Dim obj3 As New MyAssembly3.Class1()
MessageBox.Show(obj3.HelloWorld())
      Visual C# .NET or Visual C# 2005 code
      MyAssembly3.Class1 obj3=new MyAssembly3.Class1();
MessageBox.Show(obj3.HelloWorld());
    4. In Solution Explorer, right-click Add reference.

      The Add Reference dialog box appears.
    5. Click Browse, click the MyAssembly3 assembly, and then click Open.
    6. In the References folder, right-click the MyAssembly3 assembly, and then click Properties.

      The Properties window appears.
    7. In the Properties window, set the Copy Local property of the assembly to False.
  3. Add an event handler to the AssemblyResolve event in the Form1_Load event as follows:

    Visual Basic .NET or Visual Basic 2005 code
    AddHandler AppDomain.CurrentDomain.AssemblyResolve, AddressOf MyResolveEventHandler
    Visual C# .NET or Visual C# 2005 code
    AppDomain currentDomain = AppDomain.CurrentDomain;
currentDomain.AssemblyResolve += new ResolveEventHandler(MyResolveEventHandler);
  4. Define the MyResolveEventHandler function as follows:
    Visual Basic .NET or Visual Basic 2005 code
    Function MyResolveEventHandler(ByVal sender As Object, _
                               ByVal args As ResolveEventArgs) As [Assembly]
        'This handler is called only when the common language runtime tries to bind to the assembly and fails.        

        'Retrieve the list of referenced assemblies in an array of AssemblyName.
        Dim objExecutingAssemblies As [Assembly]
        objExecutingAssemblies = [Assembly].GetExecutingAssembly()
        Dim arrReferencedAssmbNames() As AssemblyName
        arrReferencedAssmbNames = objExecutingAssemblies.GetReferencedAssemblies()

        'Loop through the array of referenced assembly names.
        Dim strAssmbName As AssemblyName
        For Each strAssmbName In arrReferencedAssmbNames

            'Look for the assembly names that have raised the "AssemblyResolve" event.
            If (strAssmbName.FullName.Substring(0, strAssmbName.FullName.IndexOf(",")) = args.Name.Substring(0, args.Name.IndexOf(","))) Then

                'Build the path of the assembly from where it has to be loaded.
                Dim strTempAssmbPath As String
                strTempAssmbPath = "C:\assemblies\" & args.Name.Substring(0, args.Name.IndexOf(",")) & ".dll"
							       
                Dim MyAssembly as [Assembly] 

                'Load the assembly from the specified path. 
                MyAssembly = [Assembly].LoadFrom(strTempAssmbPath)

                'Return the loaded assembly.
                Return MyAssembly
            End If
        Next

    End Function
    Visual C# .NET or Visual C# 2005 code
    	
private Assembly MyResolveEventHandler(object sender,ResolveEventArgs args)
{
	//This handler is called only when the common language runtime tries to bind to the assembly and fails.

	//Retrieve the list of referenced assemblies in an array of AssemblyName.
	Assembly MyAssembly,objExecutingAssemblies;
	string strTempAssmbPath="";

	objExecutingAssemblies=Assembly.GetExecutingAssembly();
	AssemblyName [] arrReferencedAssmbNames=objExecutingAssemblies.GetReferencedAssemblies();
			
	//Loop through the array of referenced assembly names.
	foreach(AssemblyName strAssmbName in arrReferencedAssmbNames)
	{
		//Check for the assembly names that have raised the "AssemblyResolve" event.
		if(strAssmbName.FullName.Substring(0, strAssmbName.FullName.IndexOf(","))==args.Name.Substring(0, args.Name.IndexOf(",")))
		{
			//Build the path of the assembly from where it has to be loaded.				
			strTempAssmbPath="C:\\Myassemblies\\"+args.Name.Substring(0,args.Name.IndexOf(","))+".dll";
			break;
		}

	}
	//Load the assembly from the specified path. 					
	MyAssembly = Assembly.LoadFrom(strTempAssmbPath);					

	//Return the loaded assembly.
	return MyAssembly;			
}
  5. On the Debug menu, click Start to run the application.

    Note You must import the System.Reflection namespace to run this application.
  6. Click Button1 to call the HelloWorld() method of the MyAssembly3 assembly.

REFERENCES

For additional information about specifying an assembly's location, visit the following Microsoft Developer Network (MSDN) Web site:

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

For additional information about the <codeBase> element, visit the following MSDN Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/gngrfcodebase.asp

For additional information about how the runtime locates assemblies, visit the following MSDN Web site:

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

For additional information about the AppDomain.AssemblyResolve event, visit the following MSDN Web site:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemAppDomainClassAssemblyResolveTopic.asp

Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbvs2005swept kbvs2005applies kbEvent kbConfig kbXML kbDLL kbcomplusobj kbHOWTOmaster KB837908 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.