Building pre-release packages
Whenever you release an updated package with a new version number, NuGet considers that one as the "latest stable release" as shown, for example in the Package Manager UI within Visual Studio:
A stable release is one that's considered reliable enough to be used in production. The latest stable release is also the one that will be installed as a package update or during package restore (subject to constraints as described in Reinstalling and updating packages).
To support the software release lifecycle, NuGet 1.6 and later allows for the distribution of pre-release packages, where the version number includes a semantic versioning suffix such as
-rc. For more information, see Package versioning.
You can specify such versions in two ways:
.nuspecfile: include the semantic version suffix in the
Assembly attributes: when building a package from a Visual Studio project (
.vbproj), use the
AssemblyInformationalVersionAttributeto specify the version:
NuGet picks up this value instead of the one specified in the
AssemblyVersionattribute, which does not support semantic versioning.
When you’re ready to release a stable version, just remove the suffix and the package takes precedence over any pre-release versions. Again, see Package versioning.
Installing and updating pre-release packages
By default, NuGet does not include pre-release versions when working with packages, but you can change this behavior as follows:
Package Manager UI in Visual Studio: In the Manage NuGet Packages UI, check the Include prerelease box:
Setting or clearing this box will refresh the Package Manager UI and the list of available versions you can install.
Package Manager Console: Use the
-IncludePrereleaseswitch with the
Update-Packagecommands. Refer to the PowerShell Reference.
NuGet CLI: Use the
-prereleaseswitch with the
mirrorcommands. Refer to the NuGet CLI reference
The Semantic Versioning or SemVer convention describes how to utilize strings in version numbers to convey they meaning of the underlying code.
In this convention, each version has three parts,
Major.Minor.Patch, with the following meaning:
Major: Breaking changes
Minor: New features, but backwards compatible
Patch: Backwards compatible bug fixes only
Pre-release versions are then denoted by appending a hyphen and a string after the patch number. Technically speaking, you can use any string after the hyphen and NuGet will treat the package as pre-release. NuGet then displays the full version number in the applicable UI, leaving consumers to interpret the meaning for themselves.
With this in mind, it's generally good to follow recognized naming conventions such as the following:
-alpha: Alpha release, typically used for work-in-progress and experimentation
-beta: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs.
-rc: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge.
NuGet 4.3.0+ supports Semantic Versioning v2.0.0, which supports pre-release numbers with dot notation, as in
1.0.1-build.23. Dot notation is not supported with NuGet versions before 4.3.0. In earlier versions of NuGet, you could use a form like
1.0.1-build23 but this was always considered a pre-release version.
Whatever suffixes you use, however, NuGet will give them precedence in reverse alphabetical order:
1.0.1 1.0.1-zzz 1.0.1-rc 1.0.1-open 1.0.1-beta12 1.0.1-beta05 1.0.1-beta 1.0.1-alpha2 1.0.1-alpha
As shown, the version without any suffix will always take precedence over pre-release versions. Note also that if you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta01 and beta05 to ensure that they sort correctly when the numbers get larger.
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.