NuSpec version attribute vs assembly version

Question

When creating a nuget package, the version in the file name of the nuget package seems to come from the AssemblyInfo file in the web application project. I have also created a version attribute inside the nuspec file.

What is the relationship between these two version numbers and are there any conventions attached?

Answer 1

With regards to convention, the NuGet software itself, and the semantics it applies to packages in the gallery, does versioning as described by SemVer. Specifically you can designate beta versions by suffixing your nuspec version number with "-beta.4" or something. For example, see how the gallery displays the latest version of AutoFac, and compare how it displays an old release (note the text "This is not the latest version of Autofac available." Edit: The gallery no longer seems to provide any special message for non-current versions) and an old PRE-release version (with the text "This is a prerelease version of Autofac.").

Unfortunately, the AssemblyVersion in AssemblyInfo.cs may not contain letters or hyphens, so it can't be used in this way. However the AssemblyInformationalVersion MAY have letters and hyphens in it and, if you provide it, NuGet will use that instead of the AssemblyVersion to replace the $version$ token in your nuspec file. What's more, the AssemblyInformationalVersion (also called the "Product Version" if you check a DLL's details in windows explorer), at least to me, better represents what the NuGet version should match.

I have a slight concern with this approach in that I'm expected to leave the AssemblyVersion the same through various beta iterations and a final production iteration of the AssemblyInformationalVersion, which means I'm allowing several different versions of my DLL into the wild that may behave differently or incorrectly, yet are all identical as far as the CLR is concerned (the CLR only cares about AssemblyVersion). In practice, though, this happens frequently (including with the AutoFac packages described above) and it doesn't seem to cause a problem.

See the two excellent highest-voted answers to What are differences between AssemblyVersion, AssemblyFileVersion and AssemblyInformationalVersion? for more info on AssemblyInformationalVersion and friends.

Answer 2

There doesn't need to be a relationship between the assembly version and the nuget package version. By convention, many maintainers use the same number for both.

The convention for using the same number is also the nuget.exe default if you have no nuspec, or you use nuget.exe spec to create a tokenized nuspec file. However, if you replace the $version$ token with a value, then that value will take precendence and will be used in the package file name.

You can also set the version on the command line, which takes precedence over all of the above.

More info on Xavier's blog: NuGet $version$ token explained