Awesome
Semantic Versioning for .NET
This library implements the Semantic Versioning specification and the version range specifications used by npm (node-semver).
Installation
SemanticVersioning is available as a NuGet package. To install it, run the following command in the Package Manager Console:
Install-Package SemanticVersioning
Quick Start
Use the SemanticVersioning
namespace:
using SemanticVersioning;
Construct a range:
var range = new Range("~1.2.3");
Construct a version:
var version = new Version("1.2.4");
Test whether the version satisfies the range:
bool satisfied = range.IsSatisfied(version);
// satisfied = true
Filter a list of versions to select only those that satisfy a range:
var versions = new [] {
new Version("1.2.1"),
new Version("1.2.3"),
new Version("1.2.8"),
new Version("1.3.2"),
};
IEnumerable<Version> satisfyingVersions = range.Satisfying(versions);
// satisfyingVersions = 1.2.3, 1.2.8
Find the maximum version that satisfies a range:
Version selectedVersion = range.MaxSatisfying(versions);
// selectedVersion = 1.2.8
To get the original input string used when constructing a
version, use Version.ToString()
.
Ranges
SemanticVersioning range specifications match the range specifications used by node-semver.
A range specification is constructed by combining multiple
comparator sets with ||
, where the range is satisfied if any
of the comparator sets are satisfied.
A comparator set is a combination of comparators, where all comparators must be satisfied for a comparator set to be satisfied.
A comparator is made up of an operator and a version.
An operator is one of: =
, >
, >=
, <
, or <=
.
For example, the comparator >=1.2.3
specifies versions
greater than or equal to 1.2.3
.
An example of a range is >=1.2.3 <1.3.0 || =1.3.2
, which
is satisfied by 1.2.3
, 1.2.99
, and 1.3.2
, but not 1.3.0
.
Advanced Ranges
Ranges can also be specified using advanced range specification strings, which desugar into comparator sets.
Hyphen Ranges
A hyphen range specifies an inclusive range of valid versions, for example
1.2.3 - 1.4.2
is equivalent to >=1.2.3 <=1.4.2
.
X-Ranges
A partial version string, or a version string with components replaced by an X
or a *
matches any version where the specified components match.
For example, 1.2.x
is satisfied by 1.2.0
and 1.2.99
, but not 1.3.0
.
Tilde Ranges
When a minor version is specified, a tilde range only allows changes in the patch version. Otherwise if only the major version is specified, only changes in the minor version are allowed.
Examples:
~1.2.3
is equivalent to>=1.2.3 < 1.3.0
~1.2
is equivalent to>=1.2.0 < 1.3.0
~1
is equivalent to>=1.0.0 < 2.0.0
Caret Ranges
A caret range allows versions where the most significant non-zero version component does not change.
Examples:
^1.2.3
is equivalent to>=1.2.3 < 2.0.0
^0.2.3
is equivalent to>=0.2.3 < 0.3.0
^0.0.3
is equivalent to>=0.0.3 < 0.0.4
Pre-Release Versions
Versions with a pre-release can normally only satisfy ranges that contain a comparator with a pre-release version, and the comparator version's major, minor and patch components must match those of the version being tested.
var range = new Range(">=1.2.3-beta.2");
range.IsSatisfied("1.2.3-beta.3"); // true
range.IsSatisfied("1.2.3-alpha"); // false
range.IsSatisfied("1.2.3"); // true
range.IsSatisfied("1.2.4"); // true
range.IsSatisfied("1.2.4-beta.5"); // false
var range2 = new Range(">=1.2.3");
range2.IsSatisfied("1.2.4-alpha"); // false
To change this behaviour and allow any pre-release version to satisfy a range,
you can set the includePrerelease
argument to true:
var range = new Range(">=1.2.3-beta.2");
range.IsSatisfied("1.2.4-beta.5", includePrerelease=true); // true
var range2 = new Range(">=1.2.3");
range2.IsSatisfied("1.2.4-alpha", includePrerelease=true); // true
The Range.Satisfying
and Range.MaxSatisfying
methods similarly support
an includePrerelease
argument to allow any pre-release version.
Version Comparisons
Version
objects implement IEquatable<Version>
and IComparable<Version>
, and
can also be compared using ==
, >
, >=
, <
, <=
and !=
.
var a = new Version("1.2.3");
var b = new Version("1.3.0");
a == b; // false
a != b; // true
a > b; // false
a < b; // true
a <= b; // true
Usage Notes
The Range
and Version
constructors will throw
an ArgumentException
when an invalid range or version
string is used.
These constructors and all methods that accept versions
as a string have an optional loose
parameter, which will
allow some invalid version formats. For example, a pre-release
version without a leading hyphen
will be allowed when loose = true
.
var version = new Version("1.2.3alpha"); // Throws ArgumentException
var version = new Version("1.2.3alpha", true); // No exception thrown
The Range
class contains separate methods that accept
versions either as strings or as Version
objects.
When passing versions as a string to range methods,
invalid version strings will act as if the version does
not satisfy the range, but no exception will be thrown.
Therefore, if you want to know when a version string is invalid,
you should construct Version
objects and check for an ArgumentException
.
var range = new Range("~1.2.3");
// Returns false:
range.IsSatisfied("banana");
// Version constructor throws ArgumentException:
range.IsSatisfied(new Version("banana"));
For convenience, static methods of the Range
class are provided
that accept a range parameter as the first argument and accept versions
as strings, so you don't have to
construct any Range
or Version
objects if you just want to use one method:
// Returns 1.2.8:
Range.MaxSatisfying("~1.2.3",
new [] {"1.2.1", "1.2.3", "1.2.8", "1.3.2"});