SemVer2 1.0.0

SemVer2

Fast C# Implementation of Semantic Versioning 2.0 for .NET

English | 日本語

Overview

SemVer2 is a high-performance Semantic Versioning 2.0 implementation for .NET. It supports modern interfaces such as ISpanFormattable and ISpanParsable<T> and is designed to operate faster than libraries like semver and NuGet.Versioning.

Additionally, it includes extensions for System.Text.Json and MessagePack-CSharp and provides a CLI tool available as a .NET Tool.

Installation

NuGet packages

SemVer2 requires .NET Standard 2.1 or later. You can get the package from NuGet.

.NET CLI

dotnet add package SemVer2

Package Manager

Install-Package SemVer2

Usage

You can use the SemVer struct to handle Semantic Versioning.

var semver = SemVer.Create(1, 0, 0, "alpha", "001");
Console.WriteLine(semver);            // 1.0.0-alpha+001
Console.WriteLine(semver.Major);      // 1
Console.WriteLine(semver.Minor);      // 0
Console.WriteLine(semver.Patch);      // 0
Console.WriteLine(semver.Prerelease); // alpha
Console.WriteLine(semver.Build);      // 001

SemVer implements ISpanFormattable, ISpanParsable<T>, IUtf8SpanFormattable, and IUtf8SpanParsable<T>, allowing conversions between UTF-16/UTF-8 strings.

var semver = SemVer.Parse("1.0.0-alpha+001");

Span<char> buffer = stackalloc char[15];
semver.TryFormat(buffer, out var charsWritten);

SemVer also implements IComparable<T> and provides overloaded comparison operators (>, <, >=, <=), enabling version comparisons.

var a = SemVer.Parse("1.0.0");
var b = SemVer.Parse("1.0.1");
var c = SemVer.Parse("1.0.0-alpha");

Console.WriteLine(a < b); // True
Console.WriteLine(a < c); // False

System.Text.Json

SemVer provides SemVerJsonConverter for System.Text.Json. This is included by default in .NET Core 3.0 and later. For .NET Standard 2.1, you can install the SemVer2.SystemTextJson package.

Install-Package SemVer2.SystemTextJson

var options = new JsonSerializerOptions()
{
    Converters =
    {
        new SemVerJsonConverter()
    }
};

JsonSerializer.Serialize(SemVer.Parse("1.0.0"), options);

MessagePack-CSharp

Similarly, SemVerMessagePackFormatter and SemVerMessagePackResolver are provided for MessagePack-CSharp. You can use them by installing the SemVer2.MessagePack package.

Install-Package SemVer2.MessagePack

var resolver = MessagePack.Resolvers.CompositeResolver.Create(
    SemVerMessagePackResolver.Instance,
    MessagePack.Resolvers.StandardResolver.Instance);
var options = MessagePackSerializerOptions.Standard.WithResolver(resolver);

MessagePackSerializer.Serialize(SemVer.Parse("1.0.0"), options);

CLI

SemVer2 provides a .NET Tool that allows you to validate and increment versions via the command line, similar to node-semver.

dotnet tool install --global SemVer2.Cli

You can use it as follows:

$ dotnet semver 1.2.3
1.2.3
$ dotnet semver foo

$ dotnet semver 1.0.0 -i patch
1.0.1

$ dotnet semver 1.0.0,1.0.1,1.0.0-alpha
1.0.0-alpha
1.0.0
1.0.1

Command details are as follows:

Usage: [arguments...] [options...] [-h|--help] [--version]

Prints valid versions sorted by SemVer precedence

Arguments:
  [0] <string[]>

Options:
  -i|--increment <string?>    Increment a version by the specified level. (major | minor | patch | prerelease | release) (Default: null)
  --preid <string?>           Identifier to be used for prerelease version increments. (Default: null)

Performance

Benchmark results are as follows:

Parse (1.2.3)

Parse (1.0.0-beta+exp.sha.5114f85)

ToString (1.0.0-beta+exp.sha.5114f85)

License

This library is released under the MIT License.