Class SemVersion

A semantic version number. Conforms with v2.0.0 of semantic versioning (semver.org).

Inheritance

System.Object

SemVersion

Implements

System.IEquatable<SemVersion>

System.Runtime.Serialization.ISerializable

Namespace: Semver

Assembly: Semver.dll

Syntax

public sealed class SemVersion : Object

Constructors

SemVersion(BigInteger)

Constructs a new instance of the SemVersion class.

Declaration

public SemVersion(BigInteger major)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major version number is negative.

SemVersion(BigInteger, BigInteger)

Constructs a new instance of the SemVersion class.

Declaration

public SemVersion(BigInteger major, BigInteger minor)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.
System.Numerics.BigInteger	minor	The minor version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major or minor version number is negative.

SemVersion(BigInteger, BigInteger, BigInteger)

Constructs a new instance of the SemVersion class.

Declaration

public SemVersion(BigInteger major, BigInteger minor, BigInteger patch)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.
System.Numerics.BigInteger	minor	The minor version number.
System.Numerics.BigInteger	patch	The patch version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.

SemVersion(BigInteger, BigInteger, BigInteger, IEnumerable<PrereleaseIdentifier>, IEnumerable<MetadataIdentifier>)

Constructs a new instance of the SemVersion class.

Declaration

public SemVersion(BigInteger major, BigInteger minor = null, BigInteger patch = null, IEnumerable<PrereleaseIdentifier> prerelease = null, IEnumerable<MetadataIdentifier> metadata = null)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.
System.Numerics.BigInteger	minor	The minor version number.
System.Numerics.BigInteger	patch	The patch version number.
System.Collections.Generic.IEnumerable<PrereleaseIdentifier>	prerelease	The prerelease identifiers.
System.Collections.Generic.IEnumerable<MetadataIdentifier>	metadata	The build metadata identifiers.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.
System.ArgumentException	A prerelease or metadata identifier has the default value.

SemVersion(BigInteger, BigInteger, BigInteger, IEnumerable<String>, IEnumerable<String>)

Constructs a new instance of the SemVersion class.

Declaration

public SemVersion(BigInteger major, BigInteger minor = null, BigInteger patch = null, IEnumerable<string> prerelease = null, IEnumerable<string> metadata = null)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.
System.Numerics.BigInteger	minor	The minor version number.
System.Numerics.BigInteger	patch	The patch version number.
System.Collections.Generic.IEnumerable<System.String>	prerelease	The prerelease identifiers.
System.Collections.Generic.IEnumerable<System.String>	metadata	The build metadata identifiers.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.
System.ArgumentNullException	One of the prerelease or metadata identifiers is null.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier. Or, a metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

Properties

IsPrerelease

Whether this is a prerelease version.

Declaration

public bool IsPrerelease { get; }

Property Value

Type	Description
System.Boolean	Whether this is a prerelease version. A semantic version with prerelease identifiers is a prerelease version.

Remarks

When this is true, the Prerelease and PrereleaseIdentifiers properties are non-empty. When this is false, the Prerelease property will be an empty string and the PrereleaseIdentifiers will be an empty collection.

IsRelease

Whether this is a release version.

Declaration

public bool IsRelease { get; }

Property Value

Type	Description
System.Boolean	Whether this is a release version. A semantic version without prerelease identifiers is a release version.

Remarks

When this is true, the Prerelease property will be an empty string and the PrereleaseIdentifiers will be an empty collection. When this is false, the Prerelease and PrereleaseIdentifiers properties are non-empty.

Major

The major version number.

Declaration

public BigInteger Major { get; }

Property Value

Type	Description
System.Numerics.BigInteger	The major version number.

Remarks

An increase in the major version number indicates a backwards incompatible change.

Metadata

The build metadata for this version.

Declaration

public string Metadata { get; }

Property Value

Type	Description
System.String	The build metadata for this version or empty string if there is no metadata.

Remarks

The build metadata is a series of dot separated identifiers separated from the rest of the version number with a plus sign ('+'). Valid metadata identifiers are non-empty and consist of ASCII alphanumeric characters and hyphens ([0-9A-Za-z-]).

The metadata does not affect precedence. Two version numbers differing only in build metadata have the same precedence. However, metadata does affect sort order. An otherwise identical version without metadata sorts before one that has metadata.

MetadataIdentifiers

The build metadata identifiers for this version.

Declaration

public IReadOnlyList<MetadataIdentifier> MetadataIdentifiers { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyList<MetadataIdentifier>	The build metadata identifiers for this version or empty if there is no metadata.

Remarks

The build metadata is a series of dot separated identifiers separated from the rest of the version number with a plus sign ('+'). Valid metadata identifiers are non-empty and consist of ASCII alphanumeric characters and hyphens ([0-9A-Za-z-]).

The metadata does not affect precedence. Two version numbers differing only in build metadata have the same precedence. However, metadata does affect sort order. An otherwise identical version without metadata sorts before one that has metadata.

Minor

The minor version number.

Declaration

public BigInteger Minor { get; }

Property Value

Type	Description
System.Numerics.BigInteger	The minor version number.

Remarks

An increase in the minor version number indicates backwards compatible changes.

Patch

The patch version number.

Declaration

public BigInteger Patch { get; }

Property Value

Type	Description
System.Numerics.BigInteger	The patch version number.

Remarks

An increase in the patch version number indicates backwards compatible bug fixes.

PrecedenceComparer

An System.Collections.Generic.IEqualityComparer`1 and System.Collections.Generic.IComparer`1 that compares SemVersion by precedence. This can be used for sorting, binary search, and using SemVersion as a dictionary key.

Declaration

public static ISemVersionComparer PrecedenceComparer { get; }

Property Value

Type	Description
ISemVersionComparer	A precedence comparer that implements System.Collections.Generic.IEqualityComparer`1 and System.Collections.Generic.IComparer`1 for SemVersion.

Remarks

Precedence order is determined by comparing the major, minor, patch, and prerelease portion in order from left to right. Versions that differ only by build metadata have the same precedence. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

Prerelease

The prerelease identifiers for this version.

Declaration

public string Prerelease { get; }

Property Value

Type	Description
System.String	The prerelease identifiers for this version or empty string if this is a release version.

Remarks

A prerelease version is denoted by appending a hyphen ('-') and a series of dot separated identifiers immediately following the patch version number. Each prerelease identifier may be numeric or alphanumeric. Valid numeric identifiers consist of ASCII digits ([0-9]) without leading zeros. Valid alphanumeric identifiers are non-empty strings of ASCII alphanumeric and hyphen characters ([0-9A-Za-z-]) with at least one non-digit character.

Prerelease versions have lower precedence than release versions. Prerelease version precedence is determined by comparing each prerelease identifier in order from left to right. Numeric identifiers have lower precedence than alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order.

PrereleaseIdentifiers

The prerelease identifiers for this version.

Declaration

public IReadOnlyList<PrereleaseIdentifier> PrereleaseIdentifiers { get; }

Property Value

Type	Description
System.Collections.Generic.IReadOnlyList<PrereleaseIdentifier>	The prerelease identifiers for this version or empty if this is a release version.

Remarks

A prerelease version is denoted by appending a hyphen ('-') and a series of dot separated identifiers immediately following the patch version number. Each prerelease identifier may be numeric or alphanumeric. Valid numeric identifiers consist of ASCII digits ([0-9]) without leading zeros. Valid alphanumeric identifiers are non-empty strings of ASCII alphanumeric and hyphen characters ([0-9A-Za-z-]) with at least one non-digit character.

Prerelease versions have lower precedence than release versions. Prerelease version precedence is determined by comparing each prerelease identifier in order from left to right. Numeric identifiers have lower precedence than alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order.

SortOrderComparer

An System.Collections.Generic.IEqualityComparer`1 and System.Collections.Generic.IComparer`1 that compares SemVersion by sort order. This can be used for sorting, binary search, and using SemVersion as a dictionary key.

Declaration

public static ISemVersionComparer SortOrderComparer { get; }

Property Value

Type	Description
ISemVersionComparer	A sort order comparer that implements System.Collections.Generic.IEqualityComparer`1 and System.Collections.Generic.IComparer`1 for SemVersion.

Remarks

Sort order is consistent with precedence order, but provides an order for versions with the same precedence. Sort order is determined by comparing the major, minor, patch, prerelease portion, and build metadata in order from left to right. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

Otherwise equal versions without build metadata precede those with metadata. The build metadata is compared by comparing each metadata identifier. Identifiers are compared lexically in ASCII sort order. A longer series of metadata identifiers follows a shorter series if all the preceding identifiers are equal.

Methods

ComparePrecedence(SemVersion, SemVersion)

Compares two versions and indicates whether the first precedes, follows, or is in the same position as the second in the precedence order. Versions that differ only by build metadata have the same precedence.

Declaration

public static int ComparePrecedence(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Int32	An integer that indicates whether left precedes, follows, or is in the same position as right in the precedence order. Value Condition -1 left precedes right in the precedence order or left is null. 0 left has the same precedence as right. 1 left follows right in the precedence order or right is null.

Remarks

Precedence order is determined by comparing the major, minor, patch, and prerelease portion in order from left to right. Versions that differ only by build metadata have the same precedence. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

ComparePrecedenceTo(SemVersion)

Compares two versions and indicates whether this instance precedes, follows, or is in the same position as the other in the precedence order. Versions that differ only by build metadata have the same precedence.

Declaration

public int ComparePrecedenceTo(SemVersion other)

Parameters

Type	Name	Description
SemVersion	other

Returns

Type	Description
System.Int32	An integer that indicates whether this instance precedes, follows, or is in the same position as other in the precedence order. Value Condition -1 This instance precedes other in the precedence order. 0 This instance has the same precedence as other. 1 This instance follows other in the precedence order or other is null.

Remarks

Precedence order is determined by comparing the major, minor, patch, and prerelease portion in order from left to right. Versions that differ only by build metadata have the same precedence. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

CompareSortOrder(SemVersion, SemVersion)

Compares two versions and indicates whether the first precedes, follows, or is equal to the second in the sort order. Note that sort order is more specific than precedence order.

Declaration

public static int CompareSortOrder(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Int32	An integer that indicates whether left precedes, follows, or is equal to right in the sort order. Value Condition -1 left precedes right in the sort order or left is null. 0 left is equal to right. 1 left follows right in the sort order or right is null.

Remarks

Sort order is consistent with precedence order, but provides an order for versions with the same precedence. Sort order is determined by comparing the major, minor, patch, prerelease portion, and build metadata in order from left to right. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

Otherwise equal versions without build metadata precede those with metadata. The build metadata is compared by comparing each metadata identifier. Identifiers are compared lexically in ASCII sort order. A longer series of metadata identifiers follows a shorter series if all the preceding identifiers are equal.

CompareSortOrderTo(SemVersion)

Compares two versions and indicates whether this instance precedes, follows, or is equal to the other in the sort order. Note that sort order is more specific than precedence order.

Declaration

public int CompareSortOrderTo(SemVersion other)

Parameters

Type	Name	Description
SemVersion	other

Returns

Type	Description
System.Int32	An integer that indicates whether this instance precedes, follows, or is equal to the other in the sort order. Value Condition -1 This instance precedes the other in the sort order. 0 This instance is equal to the other. 1 This instance follows the other in the sort order or the other is null.

Remarks

Sort order is consistent with precedence order, but provides an order for versions with the same precedence. Sort order is determined by comparing the major, minor, patch, prerelease portion, and build metadata in order from left to right. The major, minor, and patch version numbers are compared numerically. A prerelease version precedes a release version.

The prerelease portion is compared by comparing each prerelease identifier from left to right. Numeric prerelease identifiers precede alphanumeric identifiers. Numeric identifiers are compared numerically. Alphanumeric identifiers are compared lexically in ASCII sort order. A longer series of prerelease identifiers follows a shorter series if all the preceding identifiers are equal.

Otherwise equal versions without build metadata precede those with metadata. The build metadata is compared by comparing each metadata identifier. Identifiers are compared lexically in ASCII sort order. A longer series of metadata identifiers follows a shorter series if all the preceding identifiers are equal.

Equals(SemVersion)

Determines whether two semantic versions are equal.

Declaration

public bool Equals(SemVersion other)

Parameters

Type	Name	Description
SemVersion	other

Returns

Type	Description
System.Boolean	true if other is equal to this version; otherwise false.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not be equal.

Equals(SemVersion, SemVersion)

Determines whether two semantic versions are equal.

Declaration

public static bool Equals(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Boolean	true if the two versions are equal, otherwise false.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not be equal.

Equals(Object)

Determines whether the given object is equal to this version.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
System.Object	obj

Returns

Type	Description
System.Boolean	true if obj is equal to this version; otherwise false.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not be equal.

FromVersion(Version)

Converts a System.Version into the equivalent semantic version.

Declaration

public static SemVersion FromVersion(Version version)

Parameters

Type	Name	Description
System.Version	version	The version to be converted to a semantic version.

Returns

Type	Description
SemVersion	The equivalent semantic version.

Remarks

System.Version numbers have the form major.minor[.build[.revision]] where square brackets ('[' and ']') indicate optional components. The first three parts are converted to the major, minor, and patch version numbers of a semantic version. If the build component is not defined (-1), the patch number is assumed to be zero. System.Version numbers with a revision greater than zero cannot be converted to semantic versions. An System.ArgumentException is thrown when this method is called with such a System.Version.

Exceptions

Type	Condition
System.ArgumentNullException	version is null.
System.ArgumentException	version has a revision number greater than zero.

GetHashCode()

Gets a hash code for this instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
System.Int32	A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not have the same hash code.

GetObjectData(SerializationInfo, StreamingContext)

Populates a System.Runtime.Serialization.SerializationInfo with the data needed to serialize the target object.

Declaration

public void GetObjectData(SerializationInfo info, StreamingContext context)

Parameters

Type	Name	Description
System.Runtime.Serialization.SerializationInfo	info	The System.Runtime.Serialization.SerializationInfo to populate with data.
System.Runtime.Serialization.StreamingContext	context	The destination (see System.Runtime.Serialization.SerializationInfo) for this serialization.

Parse(String, SemVersionStyles, Int32)

Converts the string representation of a semantic version to its SemVersion equivalent.

Declaration

public static SemVersion Parse(string version, SemVersionStyles style, int maxLength = 1024)

Parameters

Type	Name	Description
System.String	version	The version string.
SemVersionStyles	style	A bitwise combination of enumeration values that indicates the style elements that can be present in version. The preferred value to use is Strict.
System.Int32	maxLength	The maximum length of version that should be parsed. This prevents attacks using very long version strings.

Returns

Type	Description
SemVersion

Exceptions

Type	Condition
System.ArgumentException	style is not a valid SemVersionStyles value.
System.ArgumentNullException	version is null.
System.FormatException	The version is invalid or not in a format compliant with style.

Parse(String, Int32)

Declaration

public static SemVersion Parse(string version, int maxLength = 1024)

Parameters

Type	Name	Description
System.String	version
System.Int32	maxLength

Returns

Type	Description
SemVersion

ParsedFrom(BigInteger, Nullable<BigInteger>, Nullable<BigInteger>, String, String, Boolean)

Create a new instance of the SemVersion class. Parses prerelease and metadata identifiers from dot separated strings. If parsing is not needed, use a constructor instead.

Declaration

public static SemVersion ParsedFrom(BigInteger major, Nullable<BigInteger> minor = null, Nullable<BigInteger> patch = null, string prerelease = "", string metadata = "", bool allowLeadingZeros = false)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The major version number.
System.Nullable<System.Numerics.BigInteger>	minor	The minor version number.
System.Nullable<System.Numerics.BigInteger>	patch	The patch version number.
System.String	prerelease	The prerelease portion (e.g. "alpha.5").
System.String	metadata	The build metadata (e.g. "nightly.232").
System.Boolean	allowLeadingZeros	Allow leading zeros in numeric prerelease identifiers. Leading zeros will be removed.

Returns

Type	Description
SemVersion

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier when allowLeadingZeros is false. Or, a metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

PrecedenceEquals(SemVersion)

Determines whether two semantic versions have the same precedence. Versions that differ only by build metadata have the same precedence.

Declaration

public bool PrecedenceEquals(SemVersion other)

Parameters

Type	Name	Description
SemVersion	other	The semantic version to compare to.

Returns

Type	Description
System.Boolean	true if the version precedences are equal, otherwise false.

PrecedenceEquals(SemVersion, SemVersion)

Determines whether two semantic versions have the same precedence. Versions that differ only by build metadata have the same precedence.

Declaration

public static bool PrecedenceEquals(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Boolean	true if the version precedences are equal, otherwise false.

Satisfies(SemVersionRange)

Checks if this version is contained in the given range.

Declaration

public bool Satisfies(SemVersionRange range)

Parameters

Type	Name	Description
SemVersionRange	range	The range to evaluate.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.

Satisfies(UnbrokenSemVersionRange)

Checks if this version is contained in the given unbroken range.

Declaration

public bool Satisfies(UnbrokenSemVersionRange range)

Parameters

Type	Name	Description
UnbrokenSemVersionRange	range	The unbroken range to evaluate.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.

Satisfies(Predicate<SemVersion>)

Checks if this version satisfies the given predicate.

Declaration

public bool Satisfies(Predicate<SemVersion> predicate)

Parameters

Type	Name	Description
System.Predicate<SemVersion>	predicate	The predicate to evaluate on this version.

Returns

Type	Description
System.Boolean	true if the version satisfies the predicate, otherwise false.

Exceptions

Type	Condition
System.ArgumentNullException	predicate is null.

Satisfies(String, SemVersionRangeOptions, Int32)

Checks if this version is contained in the given range.

Declaration

public bool Satisfies(string range, SemVersionRangeOptions options, int maxLength = 2048)

Parameters

Type	Name	Description
System.String	range	The range to parse and evaluate.
SemVersionRangeOptions	options	A bitwise combination of enumeration values that indicates the style elements that can be present in range. The overload without this parameter defaults to Strict.
System.Int32	maxLength	The maximum length of range that should be parsed. This prevents attacks using very long range strings.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Remarks

If checks against a range will be performed repeatedly, it is much more efficient to parse the range into a SemVersionRange once and use that object to repeatedly check for containment.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.
System.ArgumentException	options is not a valid SemVersionRangeOptions value.
System.ArgumentOutOfRangeException	maxLength is less than zero.
System.FormatException	The range is invalid or not in a format compliant with options.

Satisfies(String, Int32)

Checks if this version is contained in the given range. The range is parsed using Strict.

Declaration

public bool Satisfies(string range, int maxLength = 2048)

Parameters

Type	Name	Description
System.String	range	The range to parse and evaluate.
System.Int32	maxLength	The maximum length of range that should be parsed. This prevents attacks using very long range strings.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Remarks

If checks against a range will be performed repeatedly, it is much more efficient to parse the range into a SemVersionRange once and use that object to repeatedly check for containment.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.
System.ArgumentOutOfRangeException	maxLength is less than zero.
System.FormatException	The range is invalid or not in a format compliant with Strict.

SatisfiesNpm(String, Boolean, Int32)

Checks if this version is contained in the given range in npm format.

Declaration

public bool SatisfiesNpm(string range, bool includeAllPrerelease, int maxLength = 2048)

Parameters

Type	Name	Description
System.String	range	The npm format range to parse and evaluate.
System.Boolean	includeAllPrerelease	Whether to include all prerelease versions satisfying the bounds in the range or to only include prerelease versions when it matches a bound that explicitly includes prerelease versions.
System.Int32	maxLength	The maximum length of range that should be parsed. This prevents attacks using very long range strings.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Remarks

If checks against a range will be performed repeatedly, it is much more efficient to parse the range into a SemVersionRange once using ParseNpm(String, Boolean, Int32) and use that object to repeatedly check for containment.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.
System.ArgumentOutOfRangeException	maxLength is less than zero.
System.FormatException	The range is invalid.

SatisfiesNpm(String, Int32)

Checks if this version is contained in the given range in npm format. Does not include all prerelease when parsing the range.

Declaration

public bool SatisfiesNpm(string range, int maxLength = 2048)

Parameters

Type	Name	Description
System.String	range	The npm format range to parse and evaluate.
System.Int32	maxLength	The maximum length of range that should be parsed. This prevents attacks using very long range strings.

Returns

Type	Description
System.Boolean	true if the version is contained in the range, otherwise false.

Remarks

If checks against a range will be performed repeatedly, it is much more efficient to parse the range into a SemVersionRange once using ParseNpm(String, Int32) and use that object to repeatedly check for containment.

Exceptions

Type	Condition
System.ArgumentNullException	range is null.
System.ArgumentOutOfRangeException	maxLength is less than zero.
System.FormatException	The range is invalid.

ToString()

Converts this version to an equivalent string value.

Declaration

public override string ToString()

Returns

Type	Description
System.String	The System.String equivalent of this version.

ToVersion()

Converts this semantic version to a System.Version.

Declaration

public Version ToVersion()

Returns

Type	Description
System.Version	The equivalent System.Version.

Remarks

A semantic version of the form major.minor.patch is converted to a System.Version of the form major.minor.build where the build number is the patch version of the semantic version. Prerelease versions and build metadata are not representable in a System.Version. This method throws an System.InvalidOperationException if the semantic version is a prerelease version or has build metadata.

Exceptions

Type	Condition
System.InvalidOperationException	The semantic version is a prerelease version or has build metadata or has a major, minor, or patch version number greater than System.Int32.MaxValue.

TryParse(String, out SemVersion, Int32)

Declaration

public static bool TryParse(string version, out SemVersion semver, int maxLength = 1024)

Parameters

Type	Name	Description
System.String	version
SemVersion	semver
System.Int32	maxLength

Returns

Type	Description
System.Boolean

TryParse(String, SemVersionStyles, out SemVersion, Int32)

Converts the string representation of a semantic version to its SemVersion equivalent. The return value indicates whether the conversion succeeded.

Declaration

public static bool TryParse(string version, SemVersionStyles style, out SemVersion semver, int maxLength = 1024)

Parameters

Type	Name	Description
System.String	version	The version string.
SemVersionStyles	style	A bitwise combination of enumeration values that indicates the style elements that can be present in version. The preferred value to use is Strict.
SemVersion	semver	When this method returns, contains a SemVersion instance equivalent to the version string passed in, if the version string was valid, or null if the version string was invalid.
System.Int32	maxLength	The maximum length of version that should be parsed. This prevents attacks using very long version strings.

Returns

Type	Description
System.Boolean	false when an invalid version string is passed, otherwise true.

Exceptions

Type	Condition
System.ArgumentException	style is not a valid SemVersionStyles value.

With(Nullable<BigInteger>, Nullable<BigInteger>, Nullable<BigInteger>, IEnumerable<PrereleaseIdentifier>, IEnumerable<MetadataIdentifier>)

Creates a copy of the current instance with multiple changed properties. If changing only one property use one of the more specific WithX() methods.

Declaration

public SemVersion With(Nullable<BigInteger> major = null, Nullable<BigInteger> minor = null, Nullable<BigInteger> patch = null, IEnumerable<PrereleaseIdentifier> prerelease = null, IEnumerable<MetadataIdentifier> metadata = null)

Parameters

Type	Name	Description
System.Nullable<System.Numerics.BigInteger>	major	The value to replace the major version number or null to leave it unchanged.
System.Nullable<System.Numerics.BigInteger>	minor	The value to replace the minor version number or null to leave it unchanged.
System.Nullable<System.Numerics.BigInteger>	patch	The value to replace the patch version number or null to leave it unchanged.
System.Collections.Generic.IEnumerable<PrereleaseIdentifier>	prerelease	The value to replace the prerelease identifiers or null to leave it unchanged.
System.Collections.Generic.IEnumerable<MetadataIdentifier>	metadata	The value to replace the build metadata identifiers or null to leave it unchanged.

Returns

Type	Description
SemVersion	The new version with changed properties.

Remarks

The With(Nullable<BigInteger>, Nullable<BigInteger>, Nullable<BigInteger>, IEnumerable<PrereleaseIdentifier>, IEnumerable<MetadataIdentifier>) method is intended to be called using named argument syntax, passing only those fields to be changed.

Examples

To change the minor and patch versions:

var modifiedVersion = version.With(minor: 2, patch: 4);

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.
System.ArgumentException	A prerelease or metadata identifier has the default value.

WithMajor(BigInteger)

Creates a copy of the current instance with a different major version number.

Declaration

public SemVersion WithMajor(BigInteger major)

Parameters

Type	Name	Description
System.Numerics.BigInteger	major	The value to replace the major version number.

Returns

Type	Description
SemVersion	The new version with the different major version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	major is negative.

WithMetadata(MetadataIdentifier, MetadataIdentifier[])

Creates a copy of the current instance with different build metadata identifiers.

Declaration

public SemVersion WithMetadata(MetadataIdentifier metadataIdentifier, params MetadataIdentifier[] metadataIdentifiers)

Parameters

Type	Name	Description
MetadataIdentifier	metadataIdentifier	The first identifier to replace the existing build metadata identifiers.
MetadataIdentifier[]	metadataIdentifiers	The rest of the identifiers to replace the existing build metadata identifiers.

Returns

Type	Description
SemVersion

Exceptions

Type	Condition
System.ArgumentNullException	metadataIdentifiers is null.
System.ArgumentException	A metadata identifier has the default value.

WithMetadata(IEnumerable<MetadataIdentifier>)

Creates a copy of the current instance with different build metadata identifiers.

Declaration

public SemVersion WithMetadata(IEnumerable<MetadataIdentifier> metadataIdentifiers)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<MetadataIdentifier>	metadataIdentifiers	The identifiers to replace the build metadata identifiers.

Returns

Type	Description
SemVersion	The new version with the different build metadata identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	metadataIdentifiers is null.
System.ArgumentException	A metadata identifier has the default value.

WithMetadata(IEnumerable<String>)

Creates a copy of the current instance with different build metadata identifiers.

Declaration

public SemVersion WithMetadata(IEnumerable<string> metadataIdentifiers)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.String>	metadataIdentifiers	The identifiers to replace the build metadata identifiers.

Returns

Type	Description
SemVersion	The new version with the different build metadata identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	metadataIdentifiers is null or one of the metadata identifiers is null.
System.ArgumentException	A metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

WithMetadata(String, String[])

Creates a copy of the current instance with different build metadata identifiers.

Declaration

public SemVersion WithMetadata(string metadataIdentifier, params string[] metadataIdentifiers)

Parameters

Type	Name	Description
System.String	metadataIdentifier	The first identifier to replace the existing build metadata identifiers.
System.String[]	metadataIdentifiers	The rest of the build metadata identifiers to replace the existing build metadata identifiers.

Returns

Type	Description
SemVersion	The new version with the different build metadata identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	metadataIdentifier or metadataIdentifiers is null or one of the metadata identifiers is null.
System.ArgumentException	A metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

WithMetadataParsedFrom(String)

Creates a copy of the current instance with different build metadata.

Declaration

public SemVersion WithMetadataParsedFrom(string metadata)

Parameters

Type	Name	Description
System.String	metadata	The value to replace the build metadata.

Returns

Type	Description
SemVersion	The new version with the different build metadata.

Exceptions

Type	Condition
System.ArgumentNullException	metadata is null.
System.ArgumentException	A metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

WithMinor(BigInteger)

Creates a copy of the current instance with a different minor version number.

Declaration

public SemVersion WithMinor(BigInteger minor)

Parameters

Type	Name	Description
System.Numerics.BigInteger	minor	The value to replace the minor version number.

Returns

Type	Description
SemVersion	The new version with the different minor version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	minor is negative.

WithoutMetadata()

Creates a copy of the current instance without build metadata.

Declaration

public SemVersion WithoutMetadata()

Returns

Type	Description
SemVersion	The new version without build metadata.

WithoutPrerelease()

Creates a copy of the current instance without prerelease identifiers.

Declaration

public SemVersion WithoutPrerelease()

Returns

Type	Description
SemVersion	The new version without prerelease identifiers.

WithoutPrereleaseOrMetadata()

Creates a copy of the current instance without prerelease identifiers or build metadata.

Declaration

public SemVersion WithoutPrereleaseOrMetadata()

Returns

Type	Description
SemVersion	The new version without prerelease identifiers or build metadata.

WithParsedFrom(Nullable<BigInteger>, Nullable<BigInteger>, Nullable<BigInteger>, String, String, Boolean)

Creates a copy of the current instance with multiple changed properties. Parses prerelease and metadata identifiers from dot separated strings. Use With(Nullable<BigInteger>, Nullable<BigInteger>, Nullable<BigInteger>, IEnumerable<PrereleaseIdentifier>, IEnumerable<MetadataIdentifier>) instead if parsing is not needed. If changing only one property use one of the more specific WithX() methods.

Declaration

public SemVersion WithParsedFrom(Nullable<BigInteger> major = null, Nullable<BigInteger> minor = null, Nullable<BigInteger> patch = null, string prerelease = null, string metadata = null, bool allowLeadingZeros = false)

Parameters

Type	Name	Description
System.Nullable<System.Numerics.BigInteger>	major	The value to replace the major version number or null to leave it unchanged.
System.Nullable<System.Numerics.BigInteger>	minor	The value to replace the minor version number or null to leave it unchanged.
System.Nullable<System.Numerics.BigInteger>	patch	The value to replace the patch version number or null to leave it unchanged.
System.String	prerelease	The value to replace the prerelease identifiers or null to leave it unchanged.
System.String	metadata	The value to replace the build metadata identifiers or null to leave it unchanged.
System.Boolean	allowLeadingZeros	Allow leading zeros in numeric prerelease identifiers. Leading zeros will be removed.

Returns

Type	Description
SemVersion	The new version with changed properties.

Remarks

The WithParsedFrom(Nullable<BigInteger>, Nullable<BigInteger>, Nullable<BigInteger>, String, String, Boolean) method is intended to be called using named argument syntax, passing only those fields to be changed.

Examples

To change the patch version and prerelease identifiers version:

var modifiedVersion = version.WithParsedFrom(patch: 4, prerelease: "alpha.5");

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The major, minor, or patch version number is negative.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier when allowLeadingZeros is false. Or, a metadata identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens).

WithPatch(BigInteger)

Creates a copy of the current instance with a different patch version number.

Declaration

public SemVersion WithPatch(BigInteger patch)

Parameters

Type	Name	Description
System.Numerics.BigInteger	patch	The value to replace the patch version number.

Returns

Type	Description
SemVersion	The new version with the different patch version number.

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	patch is negative.

WithPrerelease(PrereleaseIdentifier, PrereleaseIdentifier[])

Creates a copy of the current instance with different prerelease identifiers.

Declaration

public SemVersion WithPrerelease(PrereleaseIdentifier prereleaseIdentifier, params PrereleaseIdentifier[] prereleaseIdentifiers)

Parameters

Type	Name	Description
PrereleaseIdentifier	prereleaseIdentifier	The first identifier to replace the existing prerelease identifiers.
PrereleaseIdentifier[]	prereleaseIdentifiers	The rest of the identifiers to replace the existing prerelease identifiers.

Returns

Type	Description
SemVersion	The new version with the different prerelease identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	prereleaseIdentifiers is null.
System.ArgumentException	A prerelease identifier has the default value.

WithPrerelease(IEnumerable<PrereleaseIdentifier>)

Creates a copy of the current instance with different prerelease identifiers.

Declaration

public SemVersion WithPrerelease(IEnumerable<PrereleaseIdentifier> prereleaseIdentifiers)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<PrereleaseIdentifier>	prereleaseIdentifiers	The identifiers to replace the prerelease identifiers.

Returns

Type	Description
SemVersion	The new version with the different prerelease identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	prereleaseIdentifiers is null.
System.ArgumentException	A prerelease identifier has the default value.

WithPrerelease(IEnumerable<String>)

Creates a copy of the current instance with different prerelease identifiers.

Declaration

public SemVersion WithPrerelease(IEnumerable<string> prereleaseIdentifiers)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.String>	prereleaseIdentifiers	The identifiers to replace the prerelease identifiers.

Returns

Type	Description
SemVersion	The new version with the different prerelease identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	prereleaseIdentifiers is null or one of the prerelease identifiers is null.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier.

WithPrerelease(String, String[])

Creates a copy of the current instance with different prerelease identifiers.

Declaration

public SemVersion WithPrerelease(string prereleaseIdentifier, params string[] prereleaseIdentifiers)

Parameters

Type	Name	Description
System.String	prereleaseIdentifier	The first identifier to replace the existing prerelease identifiers.
System.String[]	prereleaseIdentifiers	The rest of the identifiers to replace the existing prerelease identifiers.

Returns

Type	Description
SemVersion	The new version with the different prerelease identifiers.

Exceptions

Type	Condition
System.ArgumentNullException	prereleaseIdentifier or prereleaseIdentifiers is null or one of the prerelease identifiers is null.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier.

WithPrereleaseParsedFrom(String, Boolean)

Creates a copy of the current instance with a different prerelease portion.

Declaration

public SemVersion WithPrereleaseParsedFrom(string prerelease, bool allowLeadingZeros = false)

Parameters

Type	Name	Description
System.String	prerelease	The value to replace the prerelease portion.
System.Boolean	allowLeadingZeros	Whether to allow leading zeros in the prerelease identifiers. If true, leading zeros will be allowed on numeric identifiers but will be removed.

Returns

Type	Description
SemVersion	The new version with the different prerelease identifiers.

Remarks

Because a valid numeric identifier does not have leading zeros, this constructor will never create a PrereleaseIdentifier with leading zeros even if allowLeadingZeros is true. Any leading zeros will be removed.

Exceptions

Type	Condition
System.ArgumentNullException	prerelease is null.
System.ArgumentException	A prerelease identifier is empty or contains invalid characters (i.e. characters that are not ASCII alphanumerics or hyphens) or has leading zeros for a numeric identifier when allowLeadingZeros is false.

Operators

Equality(SemVersion, SemVersion)

Determines whether two semantic versions are equal.

Declaration

public static bool operator ==(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Boolean	true if the two versions are equal, otherwise false.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not be equal.

Inequality(SemVersion, SemVersion)

Determines whether two semantic versions are not equal.

Declaration

public static bool operator !=(SemVersion left, SemVersion right)

Parameters

Type	Name	Description
SemVersion	left
SemVersion	right

Returns

Type	Description
System.Boolean	true if the two versions are not equal, otherwise false.

Remarks

Two versions are equal if every part of the version numbers are equal. Thus, two versions with the same precedence may not be equal.

Implements

System.IEquatable<>

System.Runtime.Serialization.ISerializable