.NET Reference Guide

Application Deployment — Version Policy

Last updated May 13, 2005.

Application Deployment - Version Policy

Each assembly manifest records information about the version of each dependency it was built against. The default version policy requires that the exact version of each dependency be available. So, for example, if your program was built against version 1.0.0.0 of a dependent assembly, your program will not run unless that version of the dependency is available.

However, there are some scenarios in which the application author or administrator may wish to run with a different version of a dependency at run time. For example, administrators should be able to deploy bug fix releases without requiring that every application be recompiled in order to pick up the fix. Also, administrators must be able to specify that a particular version of an assembly never be used if a security hole or other severe bug is found. The .NET Framework enables this flexibility in version binding through version policies.

Assembly version numbers

Every assembly has a four-part version number as part of its identity. Including the version as part of the identity is essential to distinguish different versions of an assembly for the purposes of side-by-side deployment and execution.

The parts of the version number are major, minor, build and revision. There are no semantics applied to the parts of the version number. That is, the CLR does not infer compatibility or any other characteristic of an assembly based on how the version number is assigned. As a developer you are free to change any portion of this number as you see fit. Even though the CLS does not apply semantics to the format of the version number, individual organizations will likely find it useful to establish conventions around how the version number is changed. This helps maintain consistency throughout an organization and makes it easier to determine things like which build a particular assembly came from.

Default version policy

When resolving references to shared assemblies, the CLR determines which version of the dependency to load when it comes across a reference to that assembly in code. The default version policy in .NET is extremely straightforward. When resolving a reference, the CLR takes the version from the calling assembly's manifest and loads the dependency that has the identical version number. In this way, the caller gets the exact version that it was built and tested against. The advantage of this policy is that it prevents the all too common scenario in which installing a program replaces a shared assembly on which an existing application depends. Recall that before .NET, existing applications would start to use the new shared component by default. However, in .NET, the installation of a new version of a shared assembly does not affect existing applications.

Custom version policy

There may be times when binding to the exact version the application was shipped with isn't what you want. For example, an administrator may deploy a critical bug fix to a shared assembly and want all applications to use this new version regardless of which version they were built with. Also, the vendor of a shared assembly may have shipped a service release to an existing assembly and would like all applications to begin using the service release instead of the original version. These scenarios and others are supported in the .NET Framework through version policies.

Version policies are stated in XML files and are simply a request to load one version of an assembly in place of another.