Assembly Configuration

for RuBoard

The CLR binds to an assembly when either a static or dynamic reference is made to it at runtime. A static reference is defined permanently in the client assembly manifest when it is compiled. A dynamic reference is produced programmatically at runtime, for example, by calling the method System.Reflection.Assembly.Load .

You can use a strongly named assembly to force a client to bind to a specific version of an assembly whether you have private or shared deployment. Suppose you want to allow several backward-compatible assemblies to match? You can use XML configuration file to specify some rules for the CLR to use when it tries to find an assembly that matches. The .NET Admin Tool can be used to create and maintain these files through a graphical interface.

The name of the configuration file client program's name is appended with a .config extension. For our AcmeGui client the configuration file would be named AcmeGui.exe.config . It is placed in the same directory as the client executable.

In addition to an application configuration file, there is an administration configuration file called Machine.config . It is found in the Config subdirectory under the directory where the .NET runtime is installed ( \WINNT\Microsoft.NET\Framework\v1.0.2914\ , where the version number reflects the current build of .NET). An administration version policy is defined with the same XML tags that an application configuration file uses. However, the administrator configuration file overrides any settings in the application configuration file.

Resolving an Assembly Reference at Runtime

If the reference has a strong name, the configuration files are examined first to determine the correct assembly version(s) required. If the reference does not have a strong name, any version will satisfy the reference. ^[9] If the assembly reference has been previously resolved, that previously loaded assembly is used. The assembly cache is checked next and, if the assembly is found there, that assembly is loaded. If the assembly is not found in the assembly cache, the CLR probes for the assembly. We will discuss probing after we discuss specifying version policy in the configuration files.

^[9] There is also a publishers configuration file that we do not discuss. If you are using Internet Explorer, the configuration files might have to be downloaded from another computer.

Specifying the Version Policy in a Configuration File

The <configuration> is the top-level tag for .NET configuration files. Assembly binding information is found in the <runtime> section. A sample AcmeGui.exe.config file might look like this:

 <?xml version="1.0"?>  <configuration>    <runtime>      <assemblyBinding xmlns="urn:schemas-microsoft com:asm.v1">        <dependentAssembly>          <assemblyIdentity name="Customer"  publicKeyToken="8b0e612d60bde0ca" />          <bindingRedirect oldVersion="1.0.0.0-1.1.0.0"  newVersion="1.1.0.0" />         </dependentAssembly>      </assemblyBinding>    </runtime>  </configuration> 

Rules defining version policy are found in the <assemblyBinding> section. The XML namespace specification is required. Each assembly whose version policy we want to set is placed in its own <dependentAssembly> section. The assemblyIdentity element has attributes that define the assembly this section refers to. The name attribute is required; the publicKeyToken and culture attributes are optional. ^[10] The bindingRedirect element's attributes define what versions can map to another version. The oldVersion attribute can be a range, the newVersion attribute can be set only to one version. In the above example, any references to versions 1.0.0.0 to 1.1.0.0 can be resolved by using version 1.1.0.0. In other words, 1.1.0.0 is backward compatible with all those versions. You can specify several bindingRedirect elements.

^[10] You may ask: Why is the publicKeyToken optional? After all, there is no version resolution without it. As we shall see shortly, other policies can be defined that do not require a public key.

You can use the .NET Admin Tool to specify this. To add an application to the tool first select Applications in the left pane. Right-mouse click and select Add from the context menu. Navigate to the application you want to configure. Select it and click the open button. Figure 7-9 shows the AcmeGui application added to the admin tool.

Figure 7-9. AcmeGui added to the .NET admin tool.

To configure the Customer assembly, select Configured Assemblies in the left pane, right-mouse click, and select Add from the context menu. In the dialog box that comes up, select the radio button that has the text "Choose an assembly from the list of assemblies this application uses." Then click the "Choose Assembly" button. Select Customer from the list that pops up, and then click the Select button. The Assembly information for the Customer assembly should be entered in the "Configure an Assembly" dialog. Click the Finish button on that dialog. Select the "Binding Policy" tab. Figure 7-10 shows what you should see after the binding policy that was in the sample configuration file was recorded.

Figure 7-10. Binding policy set for the Customer assembly.

After you select OK, you can navigate to the directory where the AcmeGui executable is, and you will see a configuration file that the tool has created for you. It should resemble our previous example.

Finding the Assembly's Physical Location

At this point the CLR knows what versions of the assembly will satisfy the reference. The CLR does not yet know where the assembly resides on disk. If the assembly with the right version has been previously loaded because of another reference to that assembly earlier in the program, that assembly is used. If the assembly has a strong name, the assembly cache is checked; if the correct version is found there, that assembly is used.

There are several elements you can specify in the configuration file to tell the CLR where to try and find the assembly.

If the assembly has not yet been found, the runtime checks to see if a codebase has been specified in the configuration file. Under the <dependentAssembly> section you can specify a <codeBase> element. This element has two attributes, a version and a URI, to check for the assembly. The Codebases tab on the .NET Admin Tool's assembly properties dialog can be used to set them in the configuration file. Examples of this element are:

 <codeBase version="1.1.1.1"  href="http://www.abc.com/Customer.dll" />          <codeBase version="1.1.1.2"  href="file:///c:\AcmeGui\Customer.dll" /> 

To use a Codebase element outside the application's directory or subdirectories, a strong name is required. At this point, whether or not the required assembly is found, the binding process stops. If the assembly is not found, an exception is generated at this point.

If a CodeBase element was not found in the configuration file, the runtime continues to probe for the assembly. At this point all searching is relative to the directory in which the application runs, which is referred to as the application base .

The runtime first looks in the application base. It then looks in any subdirectories of the application base that have the same name as the assembly. If a culture is specified in the request, the runtime only looks for the assembly subdirectory under a subdirectory with the name of the culture requested .

Finally, you can specify in the assemblyBinding section of the configuration file a privatePath, which is a semicolon-delimited list of subdirectories of the application base to look in.

 <probing privatePath="\bin;\assemb" /> 

You can also set the privatePath on the properties tab for the application in the .NET Admin Tool.

Assembly Location and Visual Studio.NET

Building an assembly within Visual Studio.NET requires a reference to a specific assembly at a specific disk location. The rules just described apply when the application is run, not built.

Within VS.NET you cannot browse to the GAC ( \Winnt\Assembly ) and add a reference. The referenced component must be located somewhere else on disk. One of the properties of a referenced component is the CopyLocal property. If set to true, the referenced component is copied to the local project directory. While that copy would be used for the compilation reference, whether it is the one linked to depends on the configuration file settings.

for RuBoard