Menu
Free Pack
Download BuildMaster Free Trial

5 Quick Tips for NuGet Versioning

by Eric Seng, on Nov 19, 2021 8:36:00 AM

I’ll be straight to the point: poorly versioned NuGet packages will cause problems.

A NuGet packages can have one of five distinct version numbers, all with their own formatting rules and behaviors.

Here are five best practices, compacted into five quick tips, you can start using immediately!

1. Stick to SemVer for Package Version Types

NuGet packages still support a 4-part number (4.3.0.0), but Microsoft no longer recommends this format.

Instead, stick to the tried and true Major, Minor, and Patch versioning. This classic method reduces confusion and makes version numbers easier to understand since it clearly communicates to any other users what state the package is at.

2. Use Fixed Assembly Version Or Match

Before NuGet, assembly version numbers were used by libraries at runtime to select which version of the assembly to load. Now NuGet just copies the assembly DLL file next to your application’s executable files and everything is deployed to the server.

Essentially, assembly versions aren’t needed in the current age of NuGet.

By using a fixed version number (ex. 9.9.9.9) you won’t run into assembly load errors at runtime.

// Fixed version number
[assembly:AssemblyVersion("9.9.9.9")]

Alternatively, in instances where a fixed number isn’t practical, you can match your SemVer package version and add a 0 on the fourth number.

// Package Version number 5.4.2
[assembly:AssemblyVersion("5.4.2.0")]

3. Embed the Version Number in the Assembly DLL

When using a fixed assembly version number with an Assembly File Version attribute, you should embed the version number in the DLL. This will make debugging much easier should you ever need to verify a library was correctly (or incorrectly) deployed.

// Package Version number 5.4.2
[assembly:AssemblyFileVersion("5.4.2")]
[assembly:AssemblyVersion("9.9.9.9")]

4. Automate Building Prerelease Packages with a Build Server

When building a NuGet package, be it part of a CI/CD process or not, you should set your Build Server to always add a prerelease label to your package. This clearly communicates that the library within the package has not been tested yet.

Prerelease labels with “dot identifiers” are a simple way to manage a Package’s unique version number. There are no standards for what these identifiers need to look like, so you team can experiment for the best, personalized solution.

One popular naming method is using “ci” and a sequent number of datetime string (4.2-ci.4 or 4.2-ci.202203151110). A sequence number help’s identify a package as it’s nth build (4th, 3rd, etc), whereas a datetime string directly states when the package was created.

5. Don’t Push a Prerelease Package, even if it’s Tested

A prerelease tag helps other developers recognize a package hasn’t been tested.

So once a prerelease has been tested, it’s time to push to publication right? Not quite. Please don’t publish packages with prerelease tags.

Instead, you need a process that turns a prerelease package into a stable one, ready for production. “Repackaging,” available in ProGet, creates a new package from a prerelease package, copying the content but changing the version number and name.

NuGet packages are essentially zip files, so you can repackage by (basically) opening the package's zip file and editing the .nuspect manifest file with a new version. 

Changing the manifest file creates a new package – identified by the new version number. It's like a "Save As" function, but for packages!

Repackaging guarantees that packages sent to production were tested.

SemVer Best Practices for NuGet

Following best practices for NuGet will help your development exponentially, especially if you’re running on, or looking to start, a CI/CD pipeline with your NuGet packages.

Others steps you can take to help promote NuGet standards to your team is encouraging best authoring practices or setting up filters to avoid unwanted NuGet packages.


Did you find this article helpful? Are you using NuGet to make your .NET packages? Learn how to optimize your NuGet in the Enterprise; sign up for our free NuGet guide:

Topics:NuGetCI/CD

Related Posts

About Inedo

Inedo is a software product company bringing you the "tech behind the tech."

Makers of Windows-first, enterprise DevOps tools BuildMaster CI/CD, ProGet private package management, and Otter IaC. Maximize developer time, minimize release risk, and empower stakeholders to bring their vision to life faster, all with the people and technology you have right now.

Follow us on social media

Follow Inedo on YouTube Follow Inedo on Facebook Follow Inedo Twitter New call-to-action

Free e-books

Free PowerShell Book NuGet for the Enterprise Guide Jenkins CICD Guide Free CICD Book Free dotnet book free IaC book