Table of Contents

Class SemanticApiVersion

Namespace
Codebelt.Extensions.Asp.Versioning
Assembly
Codebelt.Extensions.Asp.Versioning.dll

Represents an Asp.Versioning.ApiVersion that follows Semantic Versioning precedence rules.

public sealed class SemanticApiVersion : ApiVersion, IEquatable<ApiVersion>, IComparable<ApiVersion>, ISpanFormattable, IFormattable
Inheritance
ApiVersion
SemanticApiVersion
Implements
IEquatable<ApiVersion>
IComparable<ApiVersion>
Inherited Members
ApiVersion.Default
ApiVersion.Neutral
ApiVersion.GroupVersion
ApiVersion.MajorVersion
ApiVersion.MinorVersion
ApiVersion.Status

Examples

Use SemanticApiVersion when API-version ordering must follow Semantic Versioning while equality still distinguishes exact build identities. In this example, two builds have equal precedence, but they remain different exact API-version values.

using Codebelt.Extensions.Asp.Versioning;

namespace Codebelt.Extensions.Asp.Versioning;

public class SemanticVersionPrecedence
{
    public bool HasSamePrecedenceButDifferentIdentity()
    {
        var buildOne = new SemanticApiVersion(1, 2, 3, buildMetadata: "build.1");
        var buildTwo = new SemanticApiVersion(1, 2, 3, buildMetadata: "build.2");

        return buildOne.CompareTo(buildTwo) == 0 && !buildOne.Equals(buildTwo);
    }
}

Remarks

Equality and hash-code calculation use the complete version identity, including build metadata. Precedence comparisons performed by CompareTo(ApiVersion) ignore build metadata as required by Semantic Versioning.

Constructors

SemanticApiVersion(int, int, int, string, string)

Initializes a new instance of the SemanticApiVersion class.

public SemanticApiVersion(int major, int minor, int patch, string prerelease = null, string buildMetadata = null)

Parameters

major int

The major version number.

minor int

The minor version number.

patch int

The patch version number.

prerelease string

The optional pre-release identifier.

buildMetadata string

The optional build metadata.

Exceptions

ArgumentOutOfRangeException

major, minor, or patch is less than zero.

ArgumentException

prerelease is not a valid semantic version pre-release identifier - or - buildMetadata is not valid semantic version build metadata.

Properties

BuildMetadata

Gets the optional build metadata.

public string BuildMetadata { get; }

Property Value

string

The optional build metadata.

Remarks

Build metadata is part of exact version identity but is ignored by CompareTo(ApiVersion).

PatchVersion

Gets the patch version number.

public int PatchVersion { get; }

Property Value

int

The patch version number.

Prerelease

Gets the optional pre-release identifier.

public string Prerelease { get; }

Property Value

string

The optional pre-release identifier.

Methods

CompareTo(ApiVersion)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

public override int CompareTo(ApiVersion other)

Parameters

other ApiVersion

An object to compare with this instance.

Returns

int

A value that indicates the relative order of the objects being compared. The return value has these meanings:

Value Meaning
Less than zero This instance precedes other in the sort order.
Zero This instance occurs in the same position in the sort order as other.
Greater than zero This instance follows other in the sort order.

Equals(ApiVersion)

Indicates whether the current object is equal to another object of the same type.

public override bool Equals(ApiVersion other)

Parameters

other ApiVersion

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object)

Determines whether the specified object is equal to the current object.

public override bool Equals(object obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

FromVersion(Version, Action<VersionConversionOptions>)

Creates a new instance of the SemanticApiVersion class from a Version object.

public static SemanticApiVersion FromVersion(Version version, Action<VersionConversionOptions> setup = null)

Parameters

version Version

The Version to convert to a semantic API version.

setup Action<VersionConversionOptions>

The VersionConversionOptions that may be configured.

Returns

SemanticApiVersion

A new SemanticApiVersion instance derived from the specified version.

Remarks

The conversion follows these rules:

  • The Major component maps to the major version.
  • The Minor component maps to the minor version.
  • The Build component maps to the patch version; if negative, it defaults to zero.
  • The Revision component may be included in build metadata if configured via IncludeRevision.

Exceptions

ArgumentNullException

version is null.

ArgumentException

setup failed to configure an instance of VersionConversionOptions in a valid state.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

ToString(string)

Returns the text representation of the version using the specified format and format provider. Asp.Versioning.ApiVersionFormatProvider

public override string ToString(string format)

Parameters

format string

The format to return the text representation in. The value can be null or empty.

Returns

string

The string representation of the version.

Exceptions

FormatException

The specified format is not one of the supported format values.

ToString(string, IFormatProvider)

Formats the value of the current instance using the specified format.

public override string ToString(string format, IFormatProvider formatProvider)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider)

Tries to format the value of the current instance into the provided span of characters.

public override bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider provider)

Parameters

destination Span<char>

The span in which to write this instance's value formatted as a span of characters.

charsWritten int

When this method returns, contains the number of characters that were written in destination.

format ReadOnlySpan<char>

A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.

provider IFormatProvider

An optional object that supplies culture-specific formatting information for destination.

Returns

bool

true if the formatting was successful; otherwise, false.

See Also

ApiVersion
Edit this page