Symptoms
This article discusses how to consume assemblies that are located in a folder than is different from the application base folder in a Microsoft Visual Basic .NET or Microsoft Visual Basic 2005 solution.
Resolution
When you run a Visual Basic .NET or Visual Basic 2005 application, the common language runtime (CLR) expects to locate any assemblies that the application uses in either the global assembly cache or the application folder. When the CLR does not successfully bind to an assembly, you receive an error message that is similar to the following:
System.IO.FileNotFoundException. File or assembly name AssemblyName, or one of its dependencies, was not found. You can use many methods to locate an assembly that is located in a different folder. This article describes the following three methods.
Method 1: Install the assemblies in the global assembly cacheThis method requires that you sign an assembly with a strong name. To sign an assembly with a strong name and to then install the assembly in the global assembly cache, follow these steps: Name an assembly by using a strong name. To do this, follow these steps: Use the Strong Name tool (Sn.exe) that is included with the Microsoft .NET Framework software development kit (SDK) to generate a cryptographic key pair.
At the Microsoft Visual Studio .NET or Microsoft Visual Studio 2005 Command Prompt, type the following command:
sn -k AssemblyName.snk This command generates and stores a key pair in a file that is named AssemblyName.snk.Include the following assembly-level attribute in the source code (AssemblyInfo.vb):
<Assembly: AssemblyKeyFile(“AssemblyName.snk”)>Use the Global Assembly Cache Tool (Gacutil.exe) to register the .NET Framework assembly in the global assembly cache. To do this, type the following command at the Visual Studio .NET Command Prompt:
gacutil /i AssemblyName.dllFor more information about how to work with assemblies and with the global assembly cache, visit the following Microsoft Developer Network (MSDN) Web site:
http://msdn2.microsoft.com/en-us/library/6axd4fx6(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/6axd4fx6(vs.71).aspx)For more information about how to sign an assembly with a strong name, visit the following MSDN Web site:
http://msdn2.microsoft.com/en-us/library/xc31ft41(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/xc31ft41(vs.71).aspx)Note This method may be difficult and time-consuming if many assemblies exist and if the assemblies have dependencies on Microsoft Component Object Model (COM) objects. Any assembly dependencies must also be discoverable by the CLR. Therefore, if you plan to install your assembly to the global assembly cache, also install the dependencies of the assembly into the global assembly cache.
Method 2: Use an Application.Config file together with the CodeBase tagBy using an application configuration file, you can specify the location at which the CLR should look for dependent assemblies. Specifically, use the Codebase tag. By using this tag, you can put your assemblies in a separate folder. However, this method still requires that you name the library assembly by using a strong name. To use the application configuration file, follow these steps: Compile your library assembly.Sign the assembly by using a strong name.From your main application, add a reference to your library assembly, and then compile the main application.Obtain the public key token from your strongly named library assembly. To do this, follow these steps: Click Start, click All Programs, and then click Microsoft Visual Studio .NET 2003.
Note In Visual Studio 2005, click Start, click All Programs, and then click Microsoft Visual Studio 2005.Click Visual Studio .NET Tools, and then click Visual Studio .NET 2003 Command Prompt.
Note In Visual Studio 2005, click Visual Studio 2005 Tools, and then click Visual Studio .NET 2005 Command Prompt.Change the directory to the location of your library assembly. Typically, the location is the Bin folder of your library assembly project.Type the following command, and then press ENTER:
SN -T MyLibrary.dllNote Replace MyLibrary with the name of your library assembly. To make sure that the correct value is returned, make sure that you use an uppercase T in the -T switch.This command returns a hexadecimal value that represents the token for the public key of your library assembly. Make a copy of the hexadecimal value that will be used in the application configuration file.Obtain the assembly version from your strongly named library assembly. To obtain the assembly version, use one of the following methods:Method A: Windows Explorer file propertiesIn Windows Explorer, right-click your library assembly, and then click Properties.In the Properties dialog box, click the Version tab.Under Other version Information, click Assembly Version. Make a copy of this version value that will be used in the application configuration file.Method B: MSIL Disassembler (ILDASM)At the Visual Studio .NET 2003 Command Prompt, type ILDASM, and then press ENTER.On the File menu, click Open.Click your custom assembly, and then click Open.In the bottom pane, locate the assembly version (.ver). The following is an example of the assembly version:
.assembly yourAssemblyName{.ver 1:0:1969:29451}Note In this example, the assembly version is 1.0.1969.29541.Create an application configuration file. To do this, follow these steps: Paste the following XML code in Notepad:
<configuration><runtime><assemblyBinding xmlns=”urn:schemas-microsoft-com:asm.v1″><dependentAssembly><assemblyIdentity name=”MyLibrary”culture=”neutral”publicKeyToken=”fa4e781ae585ee8a”/><codeBase version=”1.0.1074.32347″ href=”FILE://C:/assemblies/myLibrary.dll”/></dependentAssembly></assemblyBinding></runtime></configuration>Change the following XML element attributes.
Collapse this tableExpand this table
Element attributeMake this changeassemblyIdentity nameChange MyLibrary to the name of your library assembly.assemblyIdentity publicKeyTokenChange the publicKeyToken attribute to the public key token value that you copied in step 4.codeBase versionChange the version attribute to the version value that you copied in step 5.codeBase hrefChange the href attribute to point to the full path name and the file name of your library assembly.Save the file as the main assembly .exe file name. Use .config as the file name extension. For example, if your main assembly is named “MyProject.exe,” the application configuration file name is “MyProject.exe.config.” You must save this file in the same folder in which your main application assembly is located.For more information, visit the following MSDN Web sites:
Specifying an assembly’s location
http://msdn2.microsoft.com/en-us/library/4191fzwb(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/4191fzwb(vs.71).aspx)
<codeBase> element
http://msdn2.microsoft.com/en-us/library/efs781xb(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/efs781xb(vs.71).aspx)
How the runtime locates assemblies
http://msdn2.microsoft.com/en-us/library/yx7xezcf(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/yx7xezcf(vs.71).aspx)
Method 3: Use the System.Reflection.Assembly.LoadFrommethodThis method uses the Assembly.LoadFrom method to explicitly load an assembly from a fully qualified path name and from a fully qualified file name. To do this, follow these steps: Compile your library assembly.Use code that is similar to the following code example to load your assembly:
Dim yourAssembly As System.Reflection.Assembly = _System.Reflection.Assembly.LoadFrom(“c:\yourAssembly.dll”)Note If you have any dependent assemblies, you should locate them in the same path where the main assembly is located.
For more information about the Assembly.LoadFrom method, visit the following MSDN Web site:
http://msdn2.microsoft.com/en-us/library/system.reflection.assembly.loadfrom(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/system.reflection.assembly.loadfrom(vs.71).aspx)
Method 4: Use the AssemblyResolve eventThe AssemblyResolve event occurs whenever the CLR unsuccessfully tries to bind to an assembly. Use the AddHandler method in the application to add an event handler that returns the correct assembly whenever the AssemblyResolve event occurs.
Note This method does not require that you name the assemblies by using strong names.
The AssemblyResolve event handler must return an [Assembly] object that represents the assembly to which the CLR must bind. Typically you can use the Assembly.LoadFrom method to load the assembly. Then, return the loaded assembly.
Note The event handler must be located in a procedure that does not contain any references to the relocated assemblies. Additionally, the event handler must be called before any code that depends on the relocated assemblies is called.
The following code is an example of an application that loads an assembly by using the AssemblyResolve event:
Module Module1Sub Main()Dim f As Form1′Set up event handler for AssemblyResolve eventAddHandler AppDomain.CurrentDomain.AssemblyResolve, _AddressOf MyResolveEventHandlerf = New Form1()Application.Run(f)End SubFunction MyResolveEventHandler(ByVal sender As Object, _ByVal args As ResolveEventArgs) As [Assembly]‘Load the assembly from the correct location and return the assembly’This handler is only called if we try to bind to the assembly and the attempt fails.Dim MyAssembly As [Assembly]MyAssembly = [Assembly].LoadFrom(“C:\assemblies\MyLibrary.dll”)Return MyAssemblyEnd FunctionEnd Module’Some sample code in Form1 which depends on the external assemblyPrivate Sub Button1_Click(ByVal sender As System.Object, _ByVal e As System.EventArgs) Handles Button1.ClickDim x As MyLibrary.Applicationx = New MyLibrary.Application()x.MyMethod()End SubEnd ClassFor more information about the AppDomain.AssemblyResolve event, visit the following MSDN Web site:
http://msdn2.microsoft.com/en-us/library/system.appdomain.assemblyresolve(vs.71).aspx(http://msdn2.microsoft.com/en-us/library/system.appdomain.assemblyresolve(vs.71).aspx)
