Best Practices for .NET Assembly Versioning

Whenever a new .NET assembly project is created in Visual Studio, a file named AssemblyInfo is created that contains attributes used to define the version of the assembly during compilation.

Using assembly versions effectively enables various team members to identify deployed assemblies and helps troubleshoot problems that may occur in a particular environment (e.g. Development, Test, or Production).

Assembly versions consist of four different parts ({Major Version}.{Minor Version}.{Build Number}.{Revision}):

Major Version
Manually incremented for major releases, such as adding many new features to the solution.
Minor Version
Manually incremented for minor releases, such as introducing small changes to existing features.
Build Number
Typically incremented automatically as part of every build performed on the Build Server. This allows each build to be tracked and tested.
Revision
Incremented for QFEs (a.k.a. “hotfixes” or patches) to builds released into the Production environment (PROD). This is set to zero for the initial release of any major/minor version of the solution.

As a general guideline, it is best to use the same version number for all assemblies compiled as part of the solution. This is easily accomplished using linked files in Visual Studio solutions.

When building the solution, there are two version numbers that need to be considered: the file version number and the .NET assembly version number.

File Version

The AssemblyFileVersionAttribute should be incremented automatically as part of the build process. At the beginning of the build process, before the build label is applied in the source control system, the Build Number portion of the file version is incremented (or the Revision, if building a QFE).

The file version should be isolated in its own file (e.g. AssemblyVersionInfo.cs) to easily automate the process of incrementing it with every build. This file can then be "linked into" each project in the solution, thus ensuring all of the various assemblies in the solution share the same file version for a particular build.

Update (2010-04-22)

In a follow-up post, I provide details for how I recommend incrementing the assembly version for each build (assuming you are using Team Foundation Server).

Assembly Version

The AssemblyVersionAttribute is the version that .NET uses when linking assemblies. This number is not incremented with every build to avoid having to specify binding redirects.

Assembly versions are incremented manually when branching the code for a release (to the PROD environment).

The assembly version number should be specified in a "shared assembly info" file (e.g. SharedAssemblyInfo.cs), thus ensuring that all of the various assemblies in the solution have the same assembly version.

By default, the Product version shown in the file properties window is the same as the value specified for AssemblyFileVersionAttribute. Setting AssemblyInformationalVersionAttribute to be the same as AssemblyVersionAttribute ensures the Product version shown in the file properties window matches the Version displayed in the GAC shell extension.

Comments

• Anonymous
  April 03, 2009
  PingBack from http://blogs.msdn.com/jjameson/archive/2009/04/02/linked-files-in-visual-studio-solutions.aspx

• Anonymous
  August 06, 2009
  What do you mean by the AssemblyFileVersionAttribute should be incremented automatically as part of the build process.  Do you have something that runs pre build that manually changes that or what exactly do you mean?

• Anonymous
  August 06, 2009
  While you certainly could increment the AssemblyFileVersionAttribute in a pre-build event, I definitely don't recommend it. Doing so would cause the version to increment each and every time any member of the Development team builds the solution. I suppose you could simply tell developers not to check-in the updated AssemblyVersionInfo.cs file, but there are definitely better ways to accomplish the desired outcome. Rather, I recommend incrementing the AssemblyFileVersionAttribute as part of your automated build process. In other words, each time an "official" build is created on the Build Server, the AssemblyVersionInfo.cs file is automatically checked out from source control, incremented, and checked back in. Obviously, the actual implementation of this process will vary depending on your particular toolset. For example, if you are using Team Foundation Server, you can setup a custom task that increments the AssemblyFileVersionAttribute as part of the build. Several people have already blogged about the details of this for TFS. If you just bing "TFS increment build" you should get some good hits within the first page of search results. In particular, make sure you read Buck Hodges blog entry if you are using continuous integration.