semver .NET Library

As of v3.0.0, the semver package is multi-targeted to support a wide range of .NET environments. You can use this package in projects targeting:

• .NET Standard 2.0: For compatibility with older .NET Framework versions (e.g., 4.6.1 through 4.8.X) and projects requiring serialization support.
• .NET Standard 2.1: For projects that want to benefit from C# 8.0 features, specifically nullable reference types, allowing the package to provide better type information regarding nullability.
• .NET 5+: For modern .NET applications. Targeting .NET 5 directly allows the package to use the built-in MemberNotNullWhenAttribute for improved null handling in range types without the overhead of external dependency types used in older versions.

When sorting collections of versions or using LINQ Max/Min, you must specify which comparison logic to use via a comparer:

• SemVersion.SortOrderComparer: For full sort order comparison.
• SemVersion.PrecedenceComparer: For precedence-based comparison.

Example of sorting a list and finding the maximum version:

var examples = new List<Example> { ... };
// Put in sort order
var sorted = examples.OrderBy(e => e.Version, SemVersion.SortOrderComparer);
// Order by precedence, then by release date
var ordered = examples.OrderBy(e => e.Version, SemVersion.PrecedenceComparer)
                      .ThenBy(e => e.Released);

var versions = new List<SemVersion> { vNextRc, v1 };
var max = versions.Max(SemVersion.SortOrderComparer);
console.WriteLine($"Max version is {max}");

You can inspect and transform SemVersion objects using properties like IsPrerelease and Prerelease, or methods like WithoutPrereleaseOrMetadata() to strip specific components.

Console.WriteLine($"Current: {version}");
if (version.IsPrerelease)
{
    Console.WriteLine($"Prerelease: {version.Prerelease}");
    Console.WriteLine($"Next release version is: {version.WithoutPrereleaseOrMetadata()}");
}

Use SemVersion.Parse to convert a version string into a SemVersion object. You can specify a parsing style, such as SemVersionStyles.Strict, to control how the string is interpreted.

var version = SemVersion.Parse("1.1.0-rc.1+e471d15", SemVersionStyles.Strict);

The library provides two ways to compare versions:

1. ComparePrecedenceTo: Compares the precedence of two versions (ignoring metadata).
2. CompareSortOrderTo: Compares the full sort order (including metadata).

Use these methods to determine if versions have equal precedence or to check their relative sort order.

if (version.ComparePrecedenceTo(vNextRc) == 0)
    Console.WriteLine($"{version} has the same precedence as {vNextRc}");

if (version.CompareSortOrderTo(vNextRc) > 0)
    Console.WriteLine($"{version} sorts after {vNextRc}");

You can create SemVersion instances using the constructor for basic versions or SemVersion.ParsedFrom for more detailed construction including prerelease identifiers.

var v1 = new SemVersion(1, 0);
var vNextRc = SemVersion.ParsedFrom(1, 1, 0, "rc.1");

Use ComparePrecedenceTo to check if two versions have equal precedence, or CompareSortOrderTo to determine if one version sorts after another.

// Check if precedence is equal
if (version.ComparePrecedenceTo(vNextRc) == 0)
    // ...

// Check sort order
if (version.CompareSortOrderTo(vNextRc) > 0)
    // ...

Use SemVersionRange.Parse to create a range object. You can also use SemVersionRange.ParseNpm to parse ranges using NPM-style syntax. To check if a version satisfies a range, use range.Contains(version) or the extension method version.Satisfies(range).

// Standard parsing
var range = SemVersionRange.Parse("^1.0.0");

// NPM-style parsing with pre-release support
var prereleaseRange = SemVersionRange.ParseNpm("^1.0.0", includeAllPrerelease: true);

// Check satisfaction
bool isIncluded = range.Contains(version);
// OR
bool satisfies = version.Satisfies(range);

For a quick check without manually creating a range object, you can use the SatisfiesNpm method directly on a SemVersion instance.

// Note: This parses the range string on every call and is slower than using a pre-parsed range object
bool satisfies = version.SatisfiesNpm("^1.0.0", includeAllPrerelease: true);

Use SemVersion.Parse to convert a string into a SemVersion object. You can specify a style, such as SemVersionStyles.Strict, to control the parsing behavior.

var version = SemVersion.Parse("1.1.0-rc.1+e471d15", SemVersionStyles.Strict);

You can create SemVersion instances using the constructor for major/minor versions, or use SemVersion.ParsedFrom to include pre-release identifiers.

// Major and Minor only
var v1 = new SemVersion(1, 0);

// Including pre-release identifiers
var vNextRc = SemVersion.ParsedFrom(1, 1, 0, "rc.1");