Invex.SemanticVersion 2.2.0

Invex.SemanticVersion

A small C# implementation of Semantic Versioning 2.0.0. It provides a single immutable SemVer type for parsing, comparing, serializing, and converting version strings of the form MAJOR.MINOR.PATCH[-PRERELEASE][+METADATA].

Features

• Spec-compliant parsing. Parses MAJOR.MINOR.PATCH[-PRERELEASE][+METADATA] using the official SemVer regex.
• Correct precedence comparison. Release > pre-release, numeric identifiers (of any length) compared numerically and ranked below alphanumeric ones, longer pre-release wins on tie.
• Familiar BCL surface. Implements ISpanParsable<SemVer>, IComparable<SemVer>, and IComparisonOperators<SemVer, SemVer, bool>.
• System.Text.Json support. Round-trips through JsonSerializer out of the box, with no custom converter.
• Implicit conversions. Converts to and from string, plus interop with System.Version.

Installation

Install from NuGet:

dotnet add package Invex.SemanticVersion

The package targets .NET 10.0. It references JetBrains.Annotations, which NuGet restores automatically.

Quick start

using Invex.SemanticVersion;

// Parse from a string
var version = SemVer.Parse("1.2.3-alpha.1+build.123");

Console.WriteLine(version.Major);        // 1
Console.WriteLine(version.Minor);        // 2
Console.WriteLine(version.Patch);        // 3
Console.WriteLine(version.PreRelease);   // alpha.1
Console.WriteLine(version.Metadata);     // build.123
Console.WriteLine(version.Prefix);       // 1.2.3
Console.WriteLine(version.IsPreRelease); // True

// Compare with natural operators
var stable = SemVer.Parse("2.0.0");
bool isNewer = stable > version;         // True (release > pre-release)

Usage

Parsing

// Throws ArgumentException on invalid input
SemVer v = SemVer.Parse("1.0.0");

// Non-throwing variant
if (SemVer.TryParse("1.0.0-rc.1", out var parsed))
{
    // use parsed
}

// ReadOnlySpan<char> overloads are also available (ISpanParsable<SemVer>)
SemVer fromSpan = SemVer.Parse("1.0.0".AsSpan(), null);

See Parsing.

Comparing and sorting

SemVer.Parse("1.0.0")           > SemVer.Parse("1.0.0-alpha");   // True
SemVer.Parse("1.0.0-alpha.10")  > SemVer.Parse("1.0.0-alpha.9"); // True (numeric)
SemVer.Parse("1.0.0-alpha.1.2") > SemVer.Parse("1.0.0-alpha.1"); // True (longer)

var list = new List<SemVer> { "2.0.0", "1.0.0", "1.0.0-rc.1" };
list.Sort();   // 1.0.0-rc.1, 1.0.0, 2.0.0

Build metadata is used only as a final tiebreaker. See Comparison & Precedence.

Range checks

var v = SemVer.Parse("1.5.0");

v.IsBetween("1.0.0", "2.0.0");   // True  (exclusive bounds)
v.IsBetween("2.0.0", "1.0.0");   // True  (bounds may be supplied in any order)
v.IsBetween("1.0.0", "1.5.0");   // False (upper bound is exclusive)

See Range Checks.

Converting to strings, JSON and System.Version

SemVer version = "1.2.3";                         // string -> SemVer
string text    = version;                         // SemVer -> string ("1.2.3")

string json = JsonSerializer.Serialize(version);  // System.Text.Json, no converter needed

Version sysVer = SemVer.Parse("3.2.1").ToSystemVersion();     // 3.2.1
SemVer fromSys = SemVer.FromSystemVersion(new Version(1, 2, 3));

See String Conversion, JSON Serialization and System.Version Interop.

Extracting build numbers

SemVer.Parse("1.0.0-rc.42").BuildNumberFromPreRelease;   // 42
SemVer.Parse("1.0.0+build.99").BuildNumberFromMetadata;  // 99
SemVer.ExtractBuildNumber("1.2.3");                      // 0 (multiple numbers)

See Build Number Extraction.

Documentation

Full documentation: https://invex-games.github.io/semantic-version/

Development

The repository requires the .NET 10 SDK. From the repository root:

dotnet build Invex.SemanticVersion.slnx
dotnet test Invex.SemanticVersion.slnx

The _atom project is the DecSm.Atom build pipeline used to build, test, and publish the package; it is not part of the published library. It also builds the DocFX site:

atom BuildDocs   # build the site into _site/
atom ServeDocs   # build and serve it locally

License

Distributed under the MIT License.