Redirecting Assembly Versions

When you build a .NET Framework application against a specific version of a strong-named assembly, the application uses that version of the assembly at run time. However, sometimes you might want the application to run against a newer version of an assembly. An application configuration file, machine configuration file, or a publisher policy file can redirect one version of an assembly to another. For details on how the common language runtime uses these files to determine which assembly version to use, see How the Runtime Locates Assemblies. You can use the .NET Framework Configuration tool (Mscorcfg.msc) to redirect assembly versions at both the application level and the machine level, or you can directly edit the configuration file.

Note   You cannot redirect versions for assemblies that are not strong-named. The common language runtime ignores the version for assemblies that are not strong-named.

Redirecting Assembly Versions Using Publisher Policy

Vendors of assemblies can state that applications should use a newer version of an assembly by including a publisher policy file with the upgraded assembly. The publisher policy file, which is located in the global assembly cache, contains assembly redirection settings.

Each major.minor version of an assembly has its own publisher policy file. For example, redirections from version 1.1.2.222 to 1.1.3.000 and from version 1.1.2.321 to version 1.1.3.000 both go into the same file. However, a redirection from version 2.0.0.999 to version 3.0.0.000 goes into a different file.

If a publisher policy file exists, the runtime checks this file after checking the assembly's manifest and application configuration file. Vendors should use publisher policies only when the new assembly is backward compatible with the assembly being redirected.

You can bypass publisher policy by specifying settings in the application configuration file.

Bypassing Publisher Policy

New versions of assemblies that claim to be backward compatible can still break an application. When this happens, you can use the following setting in the application configuration file to make the runtime bypass the publisher policy:

<publisherPolicy apply="no">

Bypass publisher policy to keep your application running for your users, but make sure you report the problem to the assembly vendor. Once an assembly has a publisher policy, the vendor should make sure that the assembly is backward compatible and that clients can use the new version as much as possible.

Redirecting Assembly Versions at the Application Level

Suppose that the assembly's vendor releases a newer version of an assembly that your application uses, but does not supply a publisher policy because the vendor does not want to guarantee that the new assembly is backward compatible with the original version. You can specify that your application use the newer version of the assembly by putting assembly binding information in your application's configuration file.

Redirecting Assembly Versions at the Machine Level

There might be rare cases when a machine administrator wants all applications on a machine to use a specific version of an assembly. For example, you might want every application to use a particular assembly version because it fixes a security hole. If an assembly is redirected in the machine's configuration file, all applications using the old version will use the new version. The machine configuration file overrides the application configuration file and the publisher policy.

Specifying Assembly Binding in Configuration Files

The application configuration file, machine configuration file, and publisher policy file use the same XML schema to process assembly redirection.

Assembly Binding

Specify information for an assembly by placing information for each assembly inside a <dependentAssembly> element. The <assemblyIdentity> element contains information that identifies an assembly. You can have more than one <dependentAssembly> element in the configuration file, but there must be exactly one <assemblyIdentity> element in each <dependentAssembly> element.

To bind an assembly, you must specify the string "urn:schemas-microsoft-com:asm.v1" with the xmlns attribute in the <assemblyBinding> tag.

Specifying Publisher Policy

To make the runtime bypass the publisher policy for a particular assembly, put the <publisherPolicy> element in the <dependentAssembly> element. To make the runtime bypass publisher policy for all assemblies that the application uses, put this setting in the <assemblyBinding> element. You can also use the .NET Framework Configuration tool (Mscorcfg.msc) to bypass publisher policy.

The default setting for the apply attribute is yes. Setting the apply attribute to no overrides any previous yes settings. For example, if apply is set to no at the application level, any assembly-specific apply setting is ignored, even if it declares the value to be yes. Thus, the no setting is the only useful state, as this changes the default.

Redirecting Assembly Versions

To redirect one version to another, use the <bindingRedirect> element. The oldVersion attribute can specify either a single version, or a range of versions. For example, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> specifies that the runtime should use version 2.0.0.0 instead of the assembly versions between 1.1.0.0 and 1.2.0.0.

Example

The following example shows how to redirect one version of myAssembly to another, and turn off publisher policy for mySecondAssembly.

<configuration>
   <runtime>
      <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
       <dependentAssembly>
         <assemblyIdentity name="myAssembly"
                           publicKeyToken="32ab4ba45e0a69a1"
                           culture="en-us" />
         <!-- Assembly versions can be redirected in application, publisher policy, or machine configuration files. -->
         <bindingRedirect oldVersion="1.0.0.0"
                          newVersion="2.0.0.0"/>
       </dependentAssembly>
       <dependentAssembly>
         <assemblyIdentity name="mySecondAssembly"
                           publicKeyToken="32ab4ba45e0a69a1"
                           culture="en-us" />
          <!-- Publisher policy can be set only in the application configuration file. -->
          <publisherPolicy apply="no">
       </dependentAssembly>
      </assemblyBinding>
   </runtime>
</configuration>

Redirecting .NET Framework Assembly Binding

You can use the appliesTo attribute on the <assemblyBinding> element in an application configuration file to redirect assembly binding references to a specific version of the .NET Framework. This optional attribute uses a .NET Framework version number to indicate what version it applies to. If no appliesTo attribute is specified, the <assemblyBinding> element applies to all versions of the .NET Framework.

The appliesTo attribute was introduced in .NET Framework version 1.1; it is ignored by the .NET Framework version 1.0. This means that all <assemblyBinding> elements are applied when using the .NET Framework version 1.0, even if an appliesTo attribute is specified.

For example, to redirect assembly binding for the .NET Framework version 1.0 assembly Regcode, you would include the following XML code in your application configuration file.

<runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1" appliesTo="v1.0.3705">
            <dependentAssembly> 
               * assembly information goes here *
            </dependentAssembly>
       </assemblyBinding>
</runtime>

The <assemblyBinding> elements are order-sensitive. You should enter assembly binding redirection information for any .NET Framework version 1.0 assemblies first, followed by assembly binding redirection information for any .NET Framework version 1.1 assemblies. Finally, enter assembly binding redirection information for any .NET Framework assembly redirection that does not use the appliesTo attribute and therefore applies to all versions of the .NET Framework. In case of a conflict in redirection, the first matching redirection statement in the configuration file is used.

For example, to redirect one reference to a .NET Framework version 1.0 assembly and another reference to a .NET Framework version 1.1 assembly, you would use the pattern shown in the following pseudocode.

<assemblyBinding xmlns="..." appliesTo="v1.0.3705"> 
   <! — .NET Framework version 1.0 redirects here --> 
</assemblyBinding> 

<assemblyBinding xmlns="..." appliesTo="v1.1.5000"> 
    <! — .NET Framework version 1.1 redirects here --> 
</assemblyBinding> 

<assemblyBinding xmlns="..."> 
    <!-- redirects meant for all versions of the runtime --> 
</assemblyBinding>

See Also

Assemblies | Programming With Assemblies | How the Runtime Locates Assemblies | Configuration Files | Configuring Applications | Runtime Settings Schema | Configuration File Schema