SemVer 2.0.0 with NuGet 3.5.0-rc1

Long awaited SemVer 2.0.0 has support has arrived in NuGet 3.5.0-rc1 for both online and local package sources. Let's take it for a spin.

What's new in SemVer 2.0.0

SemVer 2.0.0 adds multiple release labels which can be sorted numerically, and metadata, an extra string that provides a comment or build information without changing the version identity and sort behavior.

Example versions

1.0.0-rc.1
1.0.0-beta.2.build.8721
2.8.6+sha.d8fd9b231c8cba7aaa86505ca1f9e81df20af679
3.0.0-branch.dev.384+signed.false.config.debug.x86

Release labels containing only numbers are sorted numerically, avoiding the SemVer 1.0.0 requirement for adding leading zeros to build numbers to get correct sorting behavior.

SemVer 1.0.0

1.0.0-rc-9  <- highest
1.0.0-rc-10

SemVer 2.0.0

1.0.0-rc.10  <- highest
1.0.0-rc.9

Metadata can be appended to a version after the plus character, this field is not used for sorting and is for the most part ignored by NuGet, but it is still carried along as part of the package version and can be used by a human reader to determine more information about the package.

All of the versions below are identical in terms of sort order and version identity.

1.0.0+build.agent.38
1.0.0
1.0.0+git.e8fd9b231c8cba7ffa86505ca1f9e81df20af674 
1.0.0+a

Creating SemVer 2.0.0 packages

Since there are no packages containing SemVer 2.0.0 versions on the NuGet gallery we'll need to create some to try things out. This can be done with dotnet pack from the .NET Core tools..

Creating example packages can be done by running dotnet new to generate a few projects and then changing the version release label in project.json.

This example will use three projects, semverA, semverB, and semverC. All of which are linked through dependencies.

The version number here contains a SemVer 2.0.0 release label with multiple parts, for these packages the label is beta.2.build.981.

{
  "version": "1.0.0-beta.2.build.981",
  "frameworks": {
    "net45": {
      "dependencies": {
        "semverB": {
          "target": "project"
        }
      }
    }
  }
}

Once the project.json files are updated dotnet pack can be used to create the nupkgs. Two versions of each will provide a way to test upgrades in NuGet.

semverA.1.0.0-beta.2.build.981.nupkg
semverB.1.0.0-beta.2.build.981.nupkg
semverC.1.0.0-beta.2.build.981.nupkg
semverA.1.0.0-beta.2.build.1001.nupkg
semverB.1.0.0-beta.2.build.1001.nupkg
semverC.1.0.0-beta.2.build.1001.nupkg

Package sources

Currently the only package sources that support SemVer 2.0.0 are local folders and MyGet.

For this example a MyGet feed will be used. Packages can be uploaded to a new MyGet feed using the web UI.

Using NuGet with Visual Studio

Using NuGet 3.5.0-rc1 for Visual Studio 2015 with the MyGet feed we can see the packages we created, the release labels, and most important of all that an update is available.

Performing an Update on semverA brings in the latest beta.2.build.1001 version along with the dependencies.

After the update we can see that the full SemVer 2.0.0 release labels of the latest packages in the folder packages folder on disk.

Full release labels are also shown in the Package Manager Console which can list the currently installed packages with Get-Package

Floating versions

NuGet supports SemVer 2.0.0 for all project types, packages.config, UWP project.json, and .NET Core projects.

For project.json based projects this improves floating, versions can now be set to float for a release label.

{
  "version": "1.0.0-*",

  "dependencies": {
    "semverA": "1.0.0-beta.2.build.*"
  },

  "frameworks": {
    "netcoreapp1.0": {
      "dependencies": {
        "Microsoft.NETCore.App": {
          "type": "platform",
          "version": "1.0.0"
        }
      }
    }
  }
}

Trying it out

The latest NuGet VSIX for Visual Studio 2015 is available here.