DroidSolutions.Oss.SemanticVersion 1.2.0

DroidSolutions Semantic Version

This is a NuGet package containing a library that provides sort and compare functions for Semantic Version numbers.

Installation

You can install this package via CLI: dotnet add package DroidSolutions.Oss.SemanticVersion.

If you want to install it in a project that is in a subdirectory give the path to the directory containing the csproj file or the path to the csproj like this: dotnet add src/MyProject package DroidSolutions.Oss.SemanticVersion.

Usage

ISemanticVersion

There is an interface ISemanticVersion for which comparers are implemented. Just create a class and implement the interface.

SemanticVersionObject

You can also use the SemanticVersionObject class that already implements the comparer with some neat and handy additions.

Constructor

When you create a new SemanticVersionObject instance you can give the version number parts straight away.

var version = new SemanticVersionObject();                   // 1.0.0
var version = new SemanticVersionObject(2);                  // 2.0.0
var version = new SemanticVersionObject(1, 1);               // 1.1.0
var version = new SemanticVersionObject(1, 1, 1);            // 1.1.1
var version = new SemanticVersionObject(1, 1, 1, "alpha.1"); // 1.1.1-alpha.1

FromString

There is also a static FromString Method which will return you a SemanticVersionObject instance from a version string.

var version = SemanticVersionObject.FromString("v1.0.0-beta.1");

ToString

You can generate a version string with the ToString method:

var version = new SemanticVersionObject { Major = 1, Minor = 2, Patch = 3, PreRelease = "develop.13" };
Console.WriteLine(version.ToString()); // v1.2.3-develop.13

If you do not want the leading v you can use the ToVersionString method and give false for the withLeadingV parameter:

var version = new SemanticVersionObject { Major = 1, Minor = 4, Patch = 0 };
Console.WriteLine(version.ToVersionString(false)); // 1.4.0

Sorting

As mentioned a default comparer is included which allows to sort version descending to have the newest version first. You can use the Sort LinQ method for this:

var list = new List<SemanticVersionObject>
{
  SemanticVersionObject.FromString("1.0.0"),
  SemanticVersionObject.FromString("1.1.1"),
  SemanticVersionObject.FromString("1.1.0"),
  SemanticVersionObject.FromString("0.9.0"),
};

list.Sort();

Assert.Equal(
  new List<SemanticVersionObject>
  {
    SemanticVersionObject.FromString("1.1.1"),
    SemanticVersionObject.FromString("1.1.0"),
    SemanticVersionObject.FromString("1.0.0"),
    SemanticVersionObject.FromString("0.9.0"),
  },
  list);

You can also use the Array Sort method but then you have to specify the compare method yourself:

var list = new SemanticVersionObject[]
{
  SemanticVersionObject.FromString("1.0.0"),
  SemanticVersionObject.FromString("1.1.1"),
  SemanticVersionObject.FromString("1.1.0"),
  SemanticVersionObject.FromString("0.9.0"),
};

Array.Sort(list, SemanticVersionObject.SortVersionDescending());

Assert.Equal(
  new List<SemanticVersionObject>
  {
    SemanticVersionObject.FromString("1.1.1"),
    SemanticVersionObject.FromString("1.1.0"),
    SemanticVersionObject.FromString("1.0.0"),
    SemanticVersionObject.FromString("0.9.0"),
  },
  list);

Compare

The SemanticVersionObject class implements the IComparable interface so you can use the CompareTo on every instance. Just pass another instance to it. The result is an integer that tells you, if the given instance is newer (1), equal (0) or older (-1).

var oldVersion = new SemanticVersionObject(1, 0, 0);
var equalVersion = new SemanticVersionObject(1, 0, 0);
var newVersion = new SemanticVersionObject(1, 1, 0);

Console.WriteLine(oldVersion.CompareTo(newVersion)); // 1
Console.WriteLine(newVersion.CompareTo(oldVersion)); // -1
Console.WriteLine(oldVersion.CompareTo(equalVersion)); // 0

General notes on sorting and comparing

Sorting (and comparing) takes into account if there is a prerelease or not. For example consider this:

var x = new SemanticVersionObject(1, 0, 0);
var y = new SemanticVersionObject(1, 0, 0, "alpha.1");

Console.WriteLine(x.CompareTo(y)); // -1

Version without a prerelease are always newer if major, minor and patch are equal.

Also consider this:

var x = new SemanticVersionObject(1, 0, 0, "beta.2");
var y = new SemanticVersionObject(1, 0, 0, "beta.10");

Console.WriteLine(x.CompareTo(y)); // 1

Prereleases will be split into their parts and then will be compared. Each part must be separated with a dot. So for example beta is higher than alpha but just because b is later in the alphabet than a.

var x = new SemanticVersionObject(1, 0, 0, "alpha.1");
var y = new SemanticVersionObject(1, 0, 0, "beta.1");
var z = new SemanticVersionObject(1, 0, 0, "develop.1");

Console.WriteLine(x.CompareTo(y)); // 1
Console.WriteLine(y.CompareTo(z)); // 1

IsNewerThan, IsOlderThan

You can use the IsNewerThan or IsOlderThan method if you need a boolean value.

var x = new SemanticVersionObject(2, 0, 0);
var y = new SemanticVersionObject(1, 0, 0);

var isNewer = x.IsNewerThan(y); // true
var isolder = y.IsOlderThan(x); // true

The methods only return true if the given instance is newer/older. If they are both the same or the given compare version is null false is returned.

IsPreRelease

You can use the IsPreRelease method to determine if the given version is a pre release or a full semantic version.

SemanticVersionObject.FromString("v2.0.3").IsPreRelease(); // false
SemanticVersionObject.FromString("3.1.3-beta.12").IsPreRelease(); // true

Development

If you want to add a feature or fix a bug, be sure to read the contribution guidelines first.

You'll need to install the .NET SDK which can be downloaded here.

To build the project, just run dotnet build in the repository root. Tests can be executed with dotnet test and code coverage is generated by either running dotnet test --collect:"XPlat Code Coverage" or dotnet test /p:CollectCoverage=true.