Private assemblies are the simplest type of assemblies to deploy. To deploy private assemblies, simply copy them to the application's base directory or one of its subdirectories. In this section, you'll create a simple application that uses a private assembly. You'll then use this application to understand how the CLR locates private assemblies and how to configure the behavior of the CLR by using the application configuration file.
In Step by Step 10.1, you'll create two assemblies. One of these is a Windows application, and the other is a library application, which is used only by the Windows application.
STEP BY STEP10.1 Creating and Deploying an Application That Uses a Privately Deployed Assembly
|
In Step by Step 10.1, you see that MathApp.exe is able to call methods from MathLib.dll as long as both files are copied to the same folder. This is possible because MathApp.exe stores information about the assemblies to which it needs to refer. This information is a part of the assembly manifest for MathApp.exe . You can check the contents of the assembly manifest using the MSIL Disassembler ( ildasm.exe ). An alternative way to check this information is by using the .NET Framework Configuration tool as shown in Step by Step 10.2.
STEP BY STEP10.2 Viewing Assembly Dependence Information for an Application
|
In Figure 10.3, you see that a unique public key token distinguishes shared assemblies from private assemblies. If the public key token is not present, it means that the assembly is a private assembly. You can also see, from Figure 10.3, that an application does not contain the complete filename and the location of the assembly file to which it needs to refer. The CLR instead uses a process called probing to locate the privately deployed assemblies. You can have a certain degree of control over the probing process by modifying the binding policy using the application configuration file.
Binding policy for privately deployed assemblies is a set of rules that instructs the CLR to search for an assembly in specific locations. The CLR includes a default binding policy, but you can use the application configuration file to specify binding rules that instruct the CLR to search for particular assemblies in additional locations.
For Windows applications, the application configuration file is application specific and is located in the base directory of the application. The name of application configuration file is of the format ExecutableFileName. config . For example, the application configuration file for MathApp.exe would be MathApp.exe.config . In the case of Web applications, the application configuration file is stored in the root directory of the application and is named web.config .
An application configuration file is an XML file that might contain different elements to configure various aspects of an application. The element in which you'll be most interested in this section is the <probing> element that specifies additional search locations for an assembly. A stripped down version of an application configuration file containing the <probing> element is as follows :
<?xml version="1.0"?> <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <probing privatePath="bin\retail;bin\debug" /> </assemblyBinding> </runtime> </configuration>
You can use the privatePath attribute of the <probing> element to specify the subdirectories of the application's base directory that might contain assemblies. Each of these subdirectories is delimited with a semicolon.
The application configuration file shown previously will instruct the CLR to search for assemblies in bin\retail and bin\debug subdirectories of the application in addition to the search locations that are part of the default binding policy. You'll learn about the complete binding process for a privately deployed assembly in the following section.
The CLR takes the following steps to locate a privately deployed assembly:
The CLR determines the name of the assembly from the manifest of the requesting assembly.
The CLR checks to see if the requested assembly has already been loaded from the previous requests . If the assembly has been already loaded, CLR binds to the assembly and stops searching any further.
The CLR reads the application configuration file to check if any private path hints are available in the <probing> element. If there are hints, CLR will use these directory locations to search the assembly.
If the referenced assembly has no culture information, the CLR uses the following locations in the given order to find the assembly:
ApplicationBase \ AssemblyName .dll
ApplicationBase \ AssemblyName \ AssemblyName .dll
ApplicationBase \ PrivatePath1 \ AssemblyName .dll
ApplicationBase \ PrivatePath1 \ AssemblyName \ AssemblyName .dll
ApplicationBase \ PrivatePath2 \ AssemblyName .dll
ApplicationBase \ PrivatePath2 \ AssemblyName \ AssemblyName .dll
ApplicationBase \ AssemblyName .exe
ApplicationBase \ AssemblyName \ AssemblyName .exe
ApplicationBase \PrivatePath1\ AssemblyName .exe
ApplicationBase \PrivatePath1\ AssemblyName \ AssemblyName .exe
ApplicationBase \PrivatePath2\ AssemblyName .exe
ApplicationBase \PrivatePath2\ AssemblyName \ AssemblyName .exe
Here ApplicationBase is the directory in which the requesting application is installed, AssemblyName is the name of the assembly to search, and PrivatePath1 and PrivatePath2 are the hints provided in the <probing> element of the application configuration file. Note that the assembly name does not contain the extension; therefore, the CLR searches for both DLL as well as EXE files. If the assembly is found in any of these locations, the CLR binds to the assembly and stops searching any further.
If the referenced assembly has culture information, the following directories are searched:
ApplicationBase \ Culture \ AssemblyName .dll
ApplicationBase \ Culture \ AssemblyName \ AssemblyName .dll
ApplicationBase \ PrivatePath1 \ Culture \ AssemblyName .dll
ApplicationBase \ PrivatePath1 \ Culture \ AssemblyName \ AssemblyName .dll
ApplicationBase \ PrivatePath2 \ Culture \ AssemblyName .dll
ApplicationBase \ PrivatePath2 \ Culture \ AssemblyName \ AssemblyName .dll
ApplicationBase \ Culture \ AssemblyName .exe
ApplicationBase \ Culture \ AssemblyName \ AssemblyName .exe
ApplicationBase \PrivatePath1\ Culture \ AssemblyName .exe
ApplicationBase \PrivatePath1\ Culture \ AssemblyName \ AssemblyName .exe
ApplicationBase \PrivatePath2\ Culture \ AssemblyName .exe
ApplicationBase \PrivatePath2\ Culture \ AssemblyName \ AssemblyName .exe
Here Culture is a culture code corresponding to the assembly. If the assembly is found in any of these locations, the CLR binds to the assembly and stops searching any further.
If the CLR cannot locate the assembly using the preceding steps, assembly binding fails.
NOTE
Private Assembly's Version Any version information contained in the private assembly is for informational purpose only. CLR does not use the version information of a private assembly to bind to a specific version.
The .NET Framework's Assembly Binding Log Viewer tool ( fuslogvw.exe ) displays the following information for failed assembly binds:
A specific reason for the bind failure. For a privately deployed assembly, the reason is usually "The system cannot find the file specified."
Information about the calling assembly, including its name, the base directory, and a description of the private search paths.
Identity of the requested assembly, including its name, version, culture, and public key token.
A description of any Application, Publisher, or Administrator version policies that have been applied.
Whether the assembly was found in the global assembly cache.
A list of all probing URLs.
Some of the information from this list (such as version and version policies) only applies to the shared assemblies that you will learn about later in this chapter. Still, the other pieces of information (such as the list of probing URLs) can help you diagnose why the CLR cannot locate a private assembly. You can use the output of the Assembly Binding Log Viewer tool to understand how the CLR locates assemblies as shown in Step by Step 10.3.
STEP BY STEP10.3 Using the Assembly Binding Log Viewer Tool to Understand How the CLR Locates Assemblies
|
The binding log file displays valuable information about the binding process. The probing URLs at the end of the list shows which directories the CLR searched for the assembly. If you had placed the assembly in any of these directories, the application would have executed successfully.
The MathLib assembly referenced in Step by Step 10.3 does not have any culture information in it. It would be a good exercise to specify the culture information for the MathLib assembly and then use the assembly binding log to analyze the behavior of the CLR. You can associate the culture information of the MathLib assembly by changing the AssemblyCulture attribute of the assembly in the AssemblyInfo.vb file as shown here:
<assembly: AssemblyCulture("en-US")>
When you use such an assembly to build the MathApp.exe file and then follow the steps in Step by Step 10.3, you find that the CLR probes for an assembly only in the following locations:
C:\MyPrograms\MathApplication\en-US\MathLib.DLL. C:\MyPrograms\MathApplication\en-US\MathLib\MathLib.DLL. C:\MyPrograms\MathApplication\en-US\MathLib.EXE. C:\MyPrograms\MathApplication\en-US\MathLib\MathLib.EXE.
In Step by Step 10.3, the CLR only used its default binding policy to locate assemblies. Step By Step 10.4 shows how to use the .NET Framework Configuration tool to specify additional search locations for an assembly.
STEP BY STEP10.4 Using the .NET Framework Configuration Tool to Specify Additional Probing Locations
|
In Step By Step 10.4, you see that an easy way to specify additional probing locations for an assembly is to use the .NET Framework Configuration tool. This tool, in fact, stores this information in the application configuration file. You can also include probing information manually by modifying the application configuration file using any editor.
At this stage, you have a clear idea about how the CLR searches for privately deployed assemblies. You can use this knowledge to decide where you should deploy the assemblies while deploying an application that uses private assemblies.
REVIEW BREAK
|
Top |