Introduction to Publisher Policy File

In this article, we will look into publisher policy file. A policy file specifies assembly redirection and code base settings. Its structure is similar to that of application configuration file. This policy file helps us to redirect an application to use upgraded assembly. When we build an application with a strong-named assembly, the application looks for that version of the assembly at runtime. But, sometimes you may want our application to run on newer version of assembly. This redirecting of an assembly from one version to another can be achieved by using below files:

• Application Configuration file,
• Machine Configuration file and
• Publisher policy file.

You can redirect assemblies that are strong-named only. Since, CLR won't consider the version of assemblies which are not strong-named while loading. We will start with the scenario under which a policy file is handy followed by the ways to perform assembly redirection.

Scenario:

Suppose an application 'X' using an assembly 'Y' with version as 1.0.0.0. Now, we upgraded the assembly 'Y' with new features and version as 2.0.0.0. We need to make application 'X' to use upgraded assembly nothing but redirecting assembly. This redirection can be achieved by policy file. This policy file is XML-based assembly created by using Al.exe tool (Assembly Linker).

We can make an application to use a newer version of assembly by including a publisher policy file along with the latest assembly. This policy file will be registered and added to Global Assembly Cache (GAC) with assembly redirection settings in it. We need to create a separate policy file for each major.minor version of an assembly. Suppose we want to redirect version 1.1.1.0 to 1.1.1.2 and 1.1.2.0 to 1.1.3.0 of an assembly. We can create a single policy file for these redirections. If we want to redirect 1.2.0.0 to 1.3.0.0 and 2.0.0.0 to 3.0.0.0 of an assembly, than we need to create two policy files. Before creating a policy file for an upgraded assembly, we need to verify the backward compatibility of it. Now, we will discuss the ways to redirect an assembly.

Assembly redirection using Application's Configuration file:

Suppose the developer of the upgraded assembly has not provided a policy file for making the application to use it. But, we still want our application to use the newer assembly. We can achieve this by adding assembly binding information in the application's config file. We can turn off the publisher policy's redirection settings by adding below statement to the application's config file for selected assemblies or entire application.

<publisherPolicy apply="no">

Assembly redirection using Machine's Configuration file:

Suppose we are having lot of applications using a particular assembly (1.0.0.0). Now, we need to make all the applications to use an upgraded assembly (2.0.0.0). We can achieve this by including assembly binding information in machine's config file. These redirection settings in machine config file will override the application config and publisher policy settings.

The XML schema used to process redirection settings in applications, machine's config file and policy file is same.

Now, we will look into a sample redirection using config file.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1" appliesTo=" v2.0.50727">
      <dependentAssembly>
        <assemblyIdentity name="one"
        publicKeyToken="33ab4aa45e5a69b1"
        culture="en-us" />
        <bindingRedirect oldVersion="3.0.0.0-3.2.0.0" newVersion="4.0.0.0"/>
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="two"
        publicKeyToken="32ab4ba67d0a88a1"
        culture="en-us" />
        <publisherPolicy apply="no">
        </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Here, for assembly "one" redirection is happening to 4.0.0.0 version for assemblies with version in between 3.0.0.0-3.2.0.0. Than for assembly "two", we are turning off the publisher policy settings. We are using appliesTo attribute in assemblyBinding tag to redirect the assembly binding references to a specific .NET framework version.

Assembly redirection using Publisher policy file:

We need to follow below steps to create a publisher policy file.

Step 1: We will create a policy file based on XML. This file will contain necessary information for assembly redirection. Its contents will be same as of configuration file's redirection settings. The settings in publisher policy file will override the settings specified in application's config file unless it is turned off. The settings in machine's config file will override application's and publisher policy redirection settings.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="one"
        publicKeyToken="33ab4aa45e5a69b1"
        culture="en-us" />
        <bindingRedirect oldVersion="3.1.0.0-3.1.1.999" newVersion="4.0.0.0"/>
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Save the above contents in a file named as policy.3.1.one.config.

Step 2: Now, we will create publisher policy assembly using Al.exe. Its syntax is

al /link:publisherPolicyFile /out:publisherPolicyAssemblyFile /keyfile:keyPairFile /platform:processorArchitecture.
Here,

• The publisherPolicyFile argument is the name of the publisher policy file.
• The publisherPolicyAssemblyFile argument is the name of the publisher policy assembly that results from this command. The assembly file name must follow the format:
  policy.majorNumber.minorNumber.mainAssemblyName.dll
• The keyPairFile argument is the name of the file containing the key pair. You must sign the assembly and publisher policy assembly with the same key pair.
• The processorArchitecture argument identifies the platform targeted by a processor-specific assembly. It can be amd64, ia64, or x86.

So, we will generate policy assembly by issuing below command in Visual Studio command prompt:

al /link:policy.3.1.one.config /out:policy.3.1.one.dll /keyfile:mykey.snk /platform:ia64

Step 3: Finally, we add this policy assembly to GAC. We will use gacutil.exe tool to register the policy assembly in GAC. The below command will do the adding the policy assembly.

gacutil /i policy.3.1.one.dll.

In order to add the policy assembly to GAC, we need to place the policy file (XML file) in the same directory of policy assembly.

I am ending the things here. I hope this article will be helpful for all.