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

A NuGet package 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 a 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 your team can experiment with 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 helps identify a package as its 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 it 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 are 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: