Technology Toolbox

Your technology Sherpa for the Microsoft platform

Jeremy Jameson - Founder and Principal



Best Practices for .NET Assembly Versioning

This post originally appeared on my MSDN blog:

Since I no longer work for Microsoft, I have copied it here in case that blog ever goes away.

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.
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.


  1. # re: Best Practices for .NET Assembly Versioning

    August 5, 2009 7:58 PM

    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?

  2. # re: Best Practices for .NET Assembly Versioning

    August 5, 2009 11:17 PM
    Jeremy Jameson

    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.

  3. # Random Musings of Jeremy Jameson : Linked Files in Visual Studio Solutions

    April 2, 2009 8:03 PM
  4. # re: Best Practices for .NET Assembly Versioning

    February 19, 2015 7:37 PM
    What if I'm a one-person shop, writing a self-contained GUI?

    By self-contained I mean I'm not writing other assemblies which I need to keep track of. I may have multiple C# files in my project, but it's just one Visual Studio project.

    I want to control Major & Minor versions, but would be happy to let Visual Studio update Build & revision. I'd really like it if it would automatically carry this information through to the installation project, too. My previous development environment didn't require me to manually change the version there.

Add Comment

Optional, but recommended (especially if you have a Gravatar). Note that your email address will not appear with your comment.
If URL is specified, it will be included as a link with your name.

To prevent spam from being submitted, please select the following fruit: Strawberry

Please add 3 and 2 and type the answer here: