February 9, 2015

Assembly versioning the right way

When I started working on projects that matter and people actually use, I also started use assembly versioning system provided by the .NET Framework. For one thing, I like seeing a version number increase because it reminds me of how much work I’ve done. For another, it helps me solve problems when someone reports a bug and I can just ask for a version being used. But thruth to be said, there’s more to it than just increasing numbers, I learned my lesson and I share the experience through this article.

AssemblyInfo

assemblyinfo Every new project you create in Visual Studio has a file called AssemblyInfo with an extension depending on a language you use. For C#, it’s .cs extension. This file is located in a special project folder called Properties.
It’s information in this file that affects what you can see in assembly details when you right-click it in Windows Explorer and select Properties and navigate to Details tab


props

or when you reference it from another project and inpsect it in Properties window.

vsprops

Versions

There are 3 different versions that assembly can have.

AssemblyInformationalVersion

[assembly: AssemblyInformationalVersion("2.0 beta")]

This is the Product version in assembly properties details and it’s by default not included in AssemblyInfo file because it’s ment to be consistent across a whole product, which can consist of many different assemblies. Typically, a build server adjusts this version. It does not have to be a number, it can be just any string. The default value is the same as AssemblyVersion.

AssemblyFileVersion

[assembly: AssemblyFileVersion("2.0.1.5")]

This is the File version in assembly properties details and is the same as AssemblyVersion if not specified otherwise. Its format should abide by the major.minor.build.revision convention. Typically, you set the major and minor numbers the same as in AssemblyVersion and the last two are incremented with each build. However, there’s no trivial way how to specify this behaviour unless you are using a build server to do it for you. If you don’t use a build server and still want to achieve auto-incrementing, I recommend this CodeProject article that I followed with success.

Remember, this is the version you should be using for problem solving.

AssemblyVersion

[assembly: AssemblyVersion("2.0.0.0")]

This version is not visible in assembly properties details, but you can see it in VS reference properties, for instance. Its format should abide by the major.minor.build.revision convention and if not specified, it’s 0.0.0.0. This version is probably the most important one, because it’s used by the .NET Framework runtime to bind to strongly named assemblies, which means, that even a slightest change in the version can result in a compile time error or a runtime exception in a project that references it, if there’s a version mismatch while loading assemblies to an AppDomain. This version supports auto-increment directly by setting the two first number manually and replacing the rest with an asterisk.
[assembly: AssemblyVersion("2.0.*")]

I use this notation in many internal tools because they are not being built by a build server and no other projects depend on them. Once, I created a shared library, forgot about the rule emphasized above and it cost me and some of my colleagues many hours every time I did some small yet important changes, and committed a new assembly to projects I was familiar with. Finally, one day someone drew my attention to this issues and I decided to write an article about it.

What exactly can cause such problems? Let’s say you have a logging library that a project CoreLib uses. There’s also a console project SomeConsole and it uses both CoreLib and the logging library. But you are only the author of the logging library and you know about CoreLib. So when you add a new cool logging feature, rebuild the project, commit the new assembly to a repository and rebuild CoreLib to use it, now you have a problem. A person who maintains SomeConsole starts using a newer version of CoreLib but does not know about a new version of the logging library will get a compile time error. And that’s just one dependency. Now imagine, that SomeConsole also uses few other core libraries some of which discovered your logging library in a different time and therefore use a different version each. There’s a true madness.

For more explanations, navigate to this SO question. I find particularly answer from Daniel Fortunov very explaining and I like his example of mscorlib.dll.

No comments:

Post a Comment