39

I am looking out for some good practices on naming assemblies and versioning them. How often do you increment the major or minor versions?

In some cases, I have seen releases going straight from version 1.0 to 3.0. In other cases, it seems to be stuck at version 1.0.2.xxxx.

This will be for a shared assembly used in multiple projects across the company. Looking forward to some good inputs.

3
  • Are you asking about .NET? I doubt that this question is about assembly language...
    – bk1e
    Oct 14, 2008 at 4:26
  • 1
    This is about .Net. More than technology, I am interested in the process behind the versioning. Oct 14, 2008 at 6:02
  • A related question about versions: stackoverflow.com/q/3768261/531524 Nov 21, 2017 at 7:35

4 Answers 4

24

Some good information from this article on Suzanne Cook's blog on MSDN (posted 2003-05-30):

When to Change File/Assembly Versions

First of all, file versions and assembly versions need not coincide with each other. I recommend that file versions change with each build. But, don’t change assembly versions with each build just so that you can tell the difference between two versions of the same file; use the file version for that. Deciding when to change assembly versions takes some discussion of the types of builds to consider: shipping and non-shipping.

Non-Shipping Builds
In general, I recommend keeping non-shipping assembly versions the same between shipping builds. This avoids strongly-named assembly loading problems due to version mismatches. Some people prefer using publisher policy to redirect new assembly versions for each build. I recommend against that for non-shipping builds, however: it doesn’t avoid all of the loading problems. For example, if a partner x-copies your app, they may not know to install publisher policy. Then, your app will be broken for them, even though it works just fine on your machine.

But, if there are cases where different applications on the same machine need to bind to different versions of your assembly, I recommend giving those builds different assembly versions so that the correct one for each app can be used without having to use LoadFrom/etc.

Shipping Builds
As for whether it’s a good idea to change that version for shipping builds, it depends on how you want the binding to work for end-users. Do you want these builds to be side-by-side or in-place? Are there many changes between the two builds? Are they going to break some customers? Do you care that it breaks them (or do you want to force users to use your important updates)? If yes, you should consider incrementing the assembly version. But, then again, consider that doing that too many times can litter the user’s disk with outdated assemblies.

When You Change Your Assembly Versions
To change hardcoded versions to the new one, I recommend setting a variable to the version in a header file and replacing the hardcoding in sources with the variable. Then, run a pre-processor during the build to put in the correct version. I recommend changing versions right after shipping, not right before, so that there's more time to catch bugs due to the change.

21

One way to define your versioning is to give semantic meaning to each portion:

  • Go from N.x to N+1.0 when compatibility breaks with the new relase
  • Go from N.M to N.M+1 when new features are added which do not break compatibility
  • Go from N.M.X to N.M.X+1 when bug fixes are added

The above is just an example -- you'd want to define the rules that make sense for you. But it is very nice for users to quickly tell if incompatibilities are expected just by looking at the version.

Oh, and don't forget to publish the rules you come up with so people know what to expect.

1
  • 1
    Often times it's necessary to move from 1.0 to 2.0 for marketing reasons (let's not forget who pays the bills!). It's easier to charge extra for a new major rev than a minor one.
    – Jon B
    Oct 14, 2008 at 2:50
9

Semantic Versioning has a set of guidelines and rules as to how to apply this (and when). Very simple to follow and it just works.

http://semver.org/

6

The first thing I would recommend is to become familiar with the differences between the Assembly version and the File version. Unfortunately, .NET tends to treat these as the same when it comes to the AssemblyInfo files in that it usually only puts AssemblyVersion and allows the FileVersion to default to the same value.

Since you said this is a shared assembly, I'm assuming you mean it's shared at a binary level (not by including the project in the various solutions). If that's the case you want to be very deliberate about changing the Assembly version as that is what .NET uses to strong name the assembly (to allow you to put it in the GAC) and also makes up the "assembly full name". When the assembly version changes, it can have breaking changes for the applications that use it without adding assembly redirect entries in the app.config file.

As for naming, I think it depends on what your company naming rules are (if any) and the purpose of the library. For exmaple, if this library provides "core" (or system level) functionality that isn't specific to any particular product or line of business, you could name it as:

CompanyName.Framework.Core 

if it's part of a larger library, or simply

CompanyName.Shared
CompanyName.Core
CompanyName.Framework

As far as when to increment version numbers, it's still rather subjective and depends on what you consider each portion of the build number to represent. The default Microsoft scheme is Major.Minor.Build.Revision, but that doesn't mean you can't come up with your own definitions. The most important thing is to be consistent in your strategy and make sure that the definitions and rules make sense across all of your products.

In almost every version scheme I've seen the first two portions are Major.Minor. The major version number usually increments when there are large changes and/or breaking changes, while the minor version number usually increments to indicate that something changed which did was not a breaking change. The other two numbers are considerably more subjective and can be the "build" (which is often times a serial date value or a sequentially updating number that changes each day) and the "revision" or patch number. I've also seen them reversed (giving Major.Minor.Revision.Build) where build is a sequentially incrementing number from an automated build system.

Keep in mind that the assembly major and minor versions are used as the type library version number when the assembly is exported.

Finally, take a look at some of these resources for more information:

http://msdn.microsoft.com/en-us/library/51ket42z.aspx

http://msdn.microsoft.com/en-us/library/system.reflection.assemblyversionattribute.aspx

http://blogs.msdn.com/suzcook/archive/2003/05/29/57148.aspx

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.