Administering Policy
Binding is the mapping of an assembly reference to a physical assembly. A physical assembly is usually a DLL. A binding policy is a statement of the rules on how the binding should take place. Most likely you will use policy to upgrade an assembly from one version to another. Although you can also use it to specify the source for a file in case a portion of the assembly needs to be downloaded. A binding policy can be modified in three ways: through an application policy file, through a publisher policy file, and through a machine policy file. Administering each of these policy files is discussed next.
Default Binding Policy
As shown earlier, applications have the identity of referenced assemblies that are stored at compile time. The default binding policy is to bind to the version of assembly with which the application was built. Specific policy files need to be in place for this default policy to be overridden.
Changing the Binding Policy with an Application Policy File
To illustrate building, application policy, use the snap-in from %SystemRoot%Microsoft.NETFramework<version>mscorcfg.msc to edit the <application>.exe.config file in the directory where the application is installed. The easiest way of invoking this tool is to simply create a shortcut on your desktop to the snap-in. After the shortcut is created, you should have an icon on your desktop like Figure 6.5.
Figure 6.5. Shortcut to .NET Framework configuration snap-in.
Now if you double-click the shortcut, you bring up the .NET Framework Configuration tool. To demonstrate one aspect of application policy that is specifically related to assemblies, a policy will be formed that redirects all references to old assemblies to new assemblies for this application only. In the section “Installing Shared Code,” you learned to install two different versions of the same FooLib.dll assembly. Assume that the new version is safe and that all references to the old version should use the new version instead. The following steps illustrate the procedure that is required to build an application policy file that redirects an old version to a new version:
1. |
Click on the entry titled “Applications” that can be found on the left side of the .NET Framework Configuration tool. |
2. |
Click on the hyperlink that displays “Add an Application to Configure” on the right side of the page. This brings up a dialog box that prompts you for the application that you want to configure. |
3. |
Check Other if the FooTest application is on the list, and then browse for the FooTest application that was placed in the 1.2 directory. This was the version of FooTest that specifically referenced the 1.2 version of the FooLib assembly. If the FooTest is in the initial list, then make sure that it is the correct one. Its location should be in the 1.2 subdirectory. |
4. |
Click on the hyperlink “Managed Configured Assemblies” that is displayed after the application is selected. This brings up another page. |
5. |
Select the “Configure an Assembly” hyperlink. This hyperlink brings you to a page that provides several options for locating the assembly you are trying to configure. |
6. |
Select the option Choose an Assembly from the List of Assemblies This Application Uses to limit the number of choices that need to be made. This is a simple application, so it does not depend on many assemblies. The assembly for which you want to create a policy is FooLib. |
7. | |
8. |
Click the Select button and then click the Finish button on the dialog box to which you fall back. You are presented with a set of property pages. |
9. |
Select the Binding Policy tab to create a binding policy. A page appears that prompts you to fill in the old version and the new version. |
10. |
Fill in the version numbers, and your property page should look like Figure 6.7. Figure 6.7. Redirecting the old versions to the new versions.
|
11. |
Click the Apply button followed by the OK button. |
12. |
Exit the .NET Framework Configuration tool. |
Now when you run the 1.2 version of the FooTest.exe application (FooTest.exe was created previously in the section illustrating side-by-side installation. It is assumed that the FooTest.exe that you are using is bound to the 1.2 version of FooLib in the 1.2 directory), you get the following:
Foo: 1.3.697.17959
Notice that a new file has been created in the directory of the application, titled FooTest.exe.config. The contents of this file illustrate that the .NET Framework Configuration tool has just been a convenient editor. Listing 6.8 shows the essential contents of the file.
Listing 6.8. Redirection of FooLib Version Numbers
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="FooLib" publicKeyToken="ba049f56c6309b78" />
<bindingRedirect oldVersion="1.2.697.17891" newVersion="1.3.697.17959" />
</dependentAssembly>
</assemblyBinding>
</runtime>
</configuration>
|
Changing the Binding Policy with a Publisher Policy File
As an alternative to an application policy, a publisher can create a publisher policy file. This policy overrides all application policy files and is used to allow a publisher to make a statement about compatibility. A publisher policy file is an assembly that wraps an XML file that is of the same format as the application policy file. The publisher policy file is applied to the correct assembly because of the unique naming convention that is used in specifying a publisher policy file. Three steps are involved in creating a publisher policy file. The last step is placing the publisher policy file into the GAC, which should be done on a customer's machine. The other two steps prepare a file for distribution. To perform the same function that was done previously (mapping the old assembly version to the new assembly version), you can create a publisher policy file as follows:
1. | |
2. |
Create an assembly that wraps the configuration file with al: al /link:FooLib.Config /out:policy.1.2.FooLib.dll /keyfile:foo.snk The name of the policy file must begin with policy and end with dll. You need to include the major and minor number of the assembly version in the name. You are applying this against version 1.2 of the assembly, so the publisher policy reflects this in the name. The last part of the policy filename before the suffix must be the name of the main assembly. The publisher policy must be signed with the same key that was used to sign the original assembly. Just as for the application policy case, the version has been redirected. |
Changing the Binding Policy with a Machine Policy File
Using the shortcut that you created in the section on application policy, double-click the shortcut to bring up the .NET Framework Configuration tool. To demonstrate one aspect of machine policy that is specifically related to assemblies, a policy will be formed to redirect all references to old assemblies to new assemblies. This is the same policy that was built in the section on application policy, but now a machine-wide policy will be created for all applications that reference a given assembly. The steps to create or modify a machine policy file are as follows:
1. |
Click the entry titled “Configured Assemblies” that is on the left side of the .NET Framework Configuration tool. |
2. |
Click the hyperlink that displays “Configure an Assembly” on the right pane. You are presented with a form offering you two different choices to find the assembly that you want to configure. |
3. |
Either choose the assembly from among the assemblies in the cache, or enter the assembly information manually (assembly name and public key token). Because it's easy to recognize your assembly, choose Choose an Assembly from the Assembly Cache and click the Choose Assembly button. You are presented with a list box of all of the assemblies in the GAC. |
4. |
Scroll down to FooLib and select the old version (it might be 1.2.697.17891). Your screen should now look like Figure 6.8. |
5. |
Click the Select button and then click Finish on the Configure an Assembly dialog box. You are presented with a Properties dialog box for the FooLib assembly. |
6. |
Select the Binding Policy tab and enter the old version in the requested version column and the new version in the new version column. Your screen should look something like Figure 6.7, which was introduced in the “Application Policy” section. |
7. |
Click the Apply button if everything looks good. Then click OK, and you can close out the .NET Framework Configuration tool. |
Now when you run the 1.2 version of the application (FooTest.exe was created previously in the section illustrating side-by-side installation. It is assumed that the FooTest.exe that you are using is bound to the 1.2 version of FooLib in the 1.2 directory), you get this:
Foo: 1.3.697.17959
The references to the old version of the assembly have been redirected to the new version. The tool merely acted as an editor. If you want to effect the change without the tool, then add the equivalent information to the machine.config file in %SystemRoot%Microsoft.NETFramework<version>Config. This file contains a lot of information, but if you search the file for FooLib, you will see an entry that looks like Listing 6.8. It is identical to the XML that was entered for the application policy.