Deploying Private Assemblies

   


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 STEP

10.1 Creating and Deploying an Application That Uses a Privately Deployed Assembly

  1. Launch Visual Studio .NET. Select File, New, Blank Solution, and name the new solution 310C10 .

  2. Add a new Visual Basic .NET Class Library named MathLib to the solution.

  3. In the Solution Explorer, rename the default Class1.vb to MathLib.vb .

  4. Open the MathLib.vb and replace the code with the following code:

     Imports System Public Class MathLib     Public Shared Function Add(ByVal n1 As Integer, _      ByVal n2 As Integer) As Integer         Add = n1 + n2     End Function End Class 
  5. Build the project.

  6. Add a new Visual Basic .NET Windows Application named MathApp to the solution. Set this project as the Startup Project for the solution.

  7. In the Solution Explorer, right-click the project MathApp and select Add Reference from the context menu to add a reference to the MathLib project.

  8. In the Solution Explorer, rename the default Form1.vb to MathApp.vb . Open the form in code view and change all occurrences of Form1 to refer to MathApp instead. Set the form as the Startup Object for the project.

  9. Place three Label controls, three TextBox controls ( txtN1 , txtN2 , and txtResult ), and a Button control ( btnAdd ) on the form. Arrange the controls as shown in Figure 10.1.

    Figure 10.1. The MathApp.exe application calls methods from the MathLib.dll to add two numbers .

  10. Double-click the Button control and add the following code in the Click event handler:

     Private Sub btnAdd_Click(_  ByVal sender As System.Object, _  ByVal e As System.EventArgs) Handles btnAdd.Click     txtResult.Text = _      MathLib.MathLib.Add(_      Convert.ToInt32(txtN1.Text), _      Convert.ToInt32(txtN2.Text)).ToString() End Sub 
  11. Run the project. Enter the two numbers in the text boxes and click the Add button. You should see the result of adding the two numbers in the third text box.

  12. Change the solution configuration to Release mode and build the solution. The project is now ready for deployment.

  13. Create a folder on your hard drive, C:\MyPrograms\MathApplication . Copy the MathApp.exe and MathLib.dll files from the bin folder of the MathApp project to this folder.

  14. Run MathApp.exe from C:\MyPrograms\MathApplication . Add two numbers. Note that MathApp.exe successfully calls methods from the MathLib.dll .

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 STEP

10.2 Viewing Assembly Dependence Information for an Application

  1. Open the Microsoft .NET Framework Configuration tool from the Administrative Tools section of Windows Control Panel.

  2. Click the Applications node in the tree view, as shown in Figure 10.2.

    Figure 10.2. The .NET Framework Configuration tool allows you to configure an application.

  3. Click the Add an Application to Configure link.

  4. In the Configure an Application dialog box, click the Other button and browse to the C:\MyPrograms\MathApplication folder to select MathApp.exe . Select this application and click Open.

  5. Expand the new MathApp.exe node in the tree view under the Applications node. Click the Assembly Dependencies child node and then click the View Assembly Dependencies hyperlink to view all the MathApp.exe dependencies, as shown in Figure 10.3.

    Figure 10.3. You can view the dependencies of an assembly using the .NET Framework Configuration tool.

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

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.

How the CLR Binds to a Privately Deployed Assembly

The CLR takes the following steps to locate a privately deployed assembly:

  1. The CLR determines the name of the assembly from the manifest of the requesting assembly.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.


Using the Assembly Binding Log Viewer Tool to Diagnose the Binding Process

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 STEP

10.3 Using the Assembly Binding Log Viewer Tool to Understand How the CLR Locates Assemblies

  1. Launch the Visual Studio .NET command prompt. Type fuslogvw to open the Assembly Binding Log Viewer tool.

  2. Select the Log Failures check box shown in Figure 10.4.

    Figure 10.4. The Assembly Binding Log Viewer tool allows you to view the details of the failed assembly binds.

  3. Delete the MathApp.dll file from the C:\MyPrograms\MathApplication folder. This will cause the binding to fail when an application requests this assembly.

  4. Run the MathApp.exe from the C:\MyPrograms\MathApplication folder. Try to add two numbers. You should see a dialog box showing the error message that the file or its dependencies are not found. Click Quit.

  5. Now, switch to Assembly Binding Log Viewer tool and click on the Refresh button. You should see an entry for the failed assembly bind as shown in Figure 10.4.

  6. Select the entry for MathApp.exe and click the View Log button. You should see a browser window displaying the following information:

    [View full width]
     
    [View full width]
    *** Assembly Binder Log Entry (12/5/2002 @ 9:21:45 AM) *** The operation failed. Bind result: hr = 0x80070002. The system cannot find the file specified. Assembly manager loaded from: C:\WINNT\Microsoft.NET\Framework\ v1.0.3705\fusion.dll Running under executable C:\MyPrograms\MathApplication\MathApp. exe --- A detailed error log follows. === Pre-bind state information === LOG: DisplayName = MathLib, Version=1.0.1069.16112, Culture=neutral, PublicKeyToken=null (Fully-specified) LOG: Appbase = C:\MyPrograms\MathApplication\ LOG: Initial PrivatePath = NULL LOG: Dynamic Base = NULL LOG: Cache Base = NULL LOG: AppName = NULL Calling assembly : MathApp, Version=1.0.1069.16219, Culture=neutral, PublicKeyToken=null. === LOG: Processing DEVPATH. LOG: DEVPATH is not set. Falling through to regular bind. LOG: Policy not being applied to reference at this time (private, custom, partial, or location-based assembly bind). LOG: Post-policy reference: MathLib, Version=1.0.1069.16112, Culture=neutral, PublicKeyToken=null LOG: Attempting download of new URL file:///C:/MyPrograms/ MathApplication/MathLib.DLL. LOG: Attempting download of new URL file:///C:/MyPrograms/ MathApplication/MathLib/MathLib.DLL. LOG: Attempting download of new URL file:///C:/MyPrograms/ MathApplication/MathLib.EXE. LOG: Attempting download of new URL file:///C:/MyPrograms/ MathApplication/MathLib/MathLib.EXE. LOG: All probing URLs attempted and failed.

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. 

Using the .NET Framework Configuration Tool to Specify Additional Probing Locations

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 STEP

10.4 Using the .NET Framework Configuration Tool to Specify Additional Probing Locations

  1. Open the Microsoft .NET Framework Configuration Administrative tool from the Administrative Tools section of Windows Control Panel.

  2. Right-click the MathApp.exe application node (which was added in Step by Step 10.2) under the Applications node in the tree view and select Properties from the context menu.

  3. In the Properties dialog box, enter additional probing locations in the Relative Search Path for Additional Assemblies text box as shown in Figure 10.5. Click OK.

    Figure 10.5. You can specify additional probing locations for an assembly using the .NET Framework Configuration tool.

  4. Open Windows Explorer and navigate to the C:\MyPrograms\MathApplication folder. You should see an application configuration file named MathApp.exe.config containing the following code:

     <?xml version="1.0"?> <configuration>   <runtime>     <gcConcurrent enabled="true" />     <assemblyBinding xmlns=      "urn:schemas-microsoft-com:asm.v1">       <publisherPolicy apply="yes" />       <probing privatePath="bin\debug;bin\retail" />     </assemblyBinding>   </runtime> </configuration> 

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

  • The set of rules that CLR uses to locate an assembly is called binding policy. Binding policy is a deciding factor in how and where the assemblies of an application should be deployed.

  • A private assembly is identified using its simple text name and is deployed for use by a single application.

  • Binding policy for private assemblies is modified using the application configuration file. This is done by specifying additional search locations for the assembly in the <probing> XML element.


   
Top


MCAD. MCSD Training Guide (Exam 70-310. Developing XML Web Services and Server Components with Visual Basic. NET and the. NET Framework)
MCAD/MCSD Training Guide (70-310): Developing XML Web Services and Server Components with Visual Basic(R) .NET and the .NET Framework
ISBN: 0789728206
EAN: 2147483647
Year: 2002
Pages: 166

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net