Section 5.5. Custom Version Policies

5.5. Custom Version Policies

.NET allows administrators to override the default assembly-resolving policy and provide a custom version-binding policy. Administrators can provide custom policies for individual applications that affect only the way a particular application binds to its private or shared assemblies. They can also provide machine-wide custom policies that affect the way every application on the machine binds to specific shared assemblies in the GAC. Administrators can choose to create custom policies for any reason, but typically they do so when a new and improved version of a server assembly is available and the server assembly vendor guarantees backward compatibility with the older version. The administrator in that case would like to take advantage of the new version; however, .NET's default version-binding and resolving policy always tries to load the exact version with which the client application was compiled. If the new version overrides a strongly named private copy of the older version, the assembly resolver will throw an exception when it fails to find the old version. Even when the new version is installed in the GAC, the resolver will ignore it and continue to load the older version. To deal with these situations, .NET allows administrators to redirect from the requested version to a different version. .NET also allows administrators to specify a particular location to look for a specific version, instead of the default location (first the GAC, then the application directory). This allows administrators to take advantage of private assemblies in other applications, or to redirect assembly loading from the GAC to a different location altogether.

5.5.1. Application Custom Policies

The .NET Configuration tool has a top-level folder called Applications. To provide a custom policy to an application, you need to add it to the Applications folder. Right-click the Applications folder and select Add to bring up a selection dialog showing all the .NET EXE applications previously run on the machine. Select the application from that list, or browse and select the application from a location on disk. Once you've added it, you can configure a custom version policy for that application. The application will have a subfolder called Configured Assemblies (see Figure 5-9). Note in the figure that the righthand pane displays the configured assemblies and shows whether custom version-binding or codebase policies have been created for those assemblies.

The Configured Assemblies folder contains all the assemblies used by this application that have some custom policy. To provide a custom policy for an assembly, you must add it to the folder. Right-click the Configured Assemblies folder and select Add to bring up the Configure an Assembly dialog (see Figure 5-10).

You can select an assembly either from the GAC or from a list of all assemblies used by this application (the list is generated by reading the application manifest). Note that although the list displays all the assemblies used, including private ones with only friendly names, there's no point in selecting those because the resolver ignores version issues when the assembly doesn't have a strong name. You can easily tell which assemblies have strong names: strongly named assemblies have a value in the PublicKeyToken column (see Figure 5-11).

Figure 5-9. The Configured Assemblies folder

Figure 5-10. The Configure an Assembly dialog

5.5.1.1 Custom version-binding policies

Once you choose an assembly, the .NET Configuration tool immediately presents you with that assembly's properties. The Binding Policy tab lets you specify a custom version-binding policy (see Figure 5-12).

The tab contains a table listing any version redirections. As the name implies, a redirection instructs .NET to look for a different version than the one the application requests.

Figure 5-11. The Dependent Assemblies list

Figure 5-12. The Binding Policy tab

Administrators can specify a redirection from a particular version to another particular version (such as from 2.0.0.0 to 2.1.0.0), or they can specify a range of redirections (such as from 1.1.0.0-1.3.0.0 to 2.1.0.0). Redirections can be made from any version to any other version, including from newer versions to older versions (perhaps as a result of discovering a defect in a new version). The only requirement is that the version be specified in the .NET format of Major.Minor.Build.Revision number. Administrators can add as many version-redirection requests as needed.

5.5.1.2 Custom codebase policies

The Codebases tab on the assembly properties page lets administrators dictate where the assembly resolver should look for particular versions of the assembly (see Figure 5-13).

Figure 5-13. The Codebases tab

Administrators can redirect requests for private or shared assemblies to any other location. For example, if the assembly resolver is asked to load version 3.2.1.0 of an assembly and there is a codebase redirection for that version, the resolver will look for that version in the redirected location, even if a suitable version is available privately or in the GAC. The only requirement is that the redirection must be given in the .NET format of Major.Minor.Build.Revision number and the location must be in the form of a URL. Administrators can add as many codebase-redirection requests as needed.

5.5.1.3 Application configuration file

When you provide a custom policy for an application, the configurations you make with the .NET Configuration tool are saved in a special configuration file in the application folder. That file is called <application name>.config (e.g., MyClient.exe.config). The configuration file contains the custom policy in a simple XML format. For example, here is the configuration file containing the custom version-binding policies and codebase redirection shown in Figures 5-12 and 5-13

     <?xml version="1.0"?>     <configuration>        <runtime>           <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">              <dependentAssembly>                 <assemblyIdentity name="MyClassLibrary"                                   publicKeyToken="229049078753819b" />                 <publisherPolicy apply="yes"/>                 <bindingRedirect oldVersion="2.0.0.0" newVersion="2.1.0.0" />                 <bindingRedirect oldVersion="1.1.0.0-1.3.0.0" newVersion="2.1.0.0" />                 <codeBase version="3.2.1.0" href="file:///c:\temp\SomeApp" />              </dependentAssembly>           </assemblyBinding>        </runtime>     </configuration> 

The configuration file allows you to duplicate an application's custom version policies across multiple machines. Normally, you don't need to edit the application configuration file manuallyinstead, use the .NET Configuration tool to edit that file, and then simply deploy it on every required target machine.

The application configuration file may also contain remoting configuration settings, described in Chapter 10.

5.5.2. Global Custom Policies

Administrators can also provide global custom policies for assemblies in the GACyou can add assemblies from the GAC to the .NET Configuration tool's Configured Assemblies folder (shown in Figure 5-9) and then specify custom version-binding and codebase policies for those assemblies. Specifying such custom policies is done exactly the same way as specifying custom policies for individual applications. Note that global custom policies affect all applications on the machine. In addition, global custom policies are applied downstream, meaning that the application applies its custom policies first, and then global custom policies are applied. For example, suppose an application was built with version 1.0 of a class library. The application can install a custom version policy that asks to use version 2.0 instead of 1.0. In addition, suppose that on the machine there is a global custom policy that redirects requests for version 2.0 of the class library to version 3.0. When the application runs in the situation just described, it will use version 3.0 of the class library.

When you provide a global custom policy, the configurations made using the .NET Configuration tool are saved in a special configuration file that affects the entire machine. This machine-wide configuration file is called machine.config, and it resides in the <Windows Folder>\Microsoft.NET\Framework\<version number>\CONFIG folder. The machine-wide configuration file contains the global custom policy in an XML format identical to that of an application configuration file. The machine.config file also contains configuration settings for predefined remoting channels and ASP.NET. Normally, you don't need to edit machine.config manually. Use the .NET Configuration tool for editing, and copy the file between machines only if you need to duplicate global custom policies on multiple machines.