Class ApiVersionAliasParser

Namespace

Codebelt.Extensions.Asp.Versioning

Assembly

Codebelt.Extensions.Asp.Versioning.dll

Resolves friendly API version aliases before delegating to another Asp.Versioning.IApiVersionParser.

public class ApiVersionAliasParser : IApiVersionParser

Inheritance

object

ApiVersionAliasParser

Implements

IApiVersionParser

Examples

Use ApiVersionAliasParser when callers send short version tokens such as 1, 1.2, or 1.2.3 over the wire but the rest of the application works with canonical SemanticApiVersion instances. The static CreateSemanticVersionAlias factory generates the alias map for a set of semantic versions, and Parse resolves a request token to the canonical version while the parser falls back to ApiVersionParser.Default for anything outside the alias table. The example below parses 1.2 and 2.0 from request strings and returns the resolved semantic versions.

using System;
using System.Collections.Generic;
using Asp.Versioning;
using Codebelt.Extensions.Asp.Versioning;

namespace Codebelt.Extensions.Asp.Versioning;

public class AliasAwareVersionResolver
{
    public IReadOnlyList<string> ResolveShortVersionTokens()
    {
        var stable = new SemanticApiVersion(1, 2, 0);
        var next = new SemanticApiVersion(2, 0, 0);

        IApiVersionParser parser = ApiVersionAliasParser.CreateSemanticVersionAlias([stable, next]);

        return new[]
        {
            parser.Parse("1.2").ToString(),
            parser.Parse("2.0").ToString()
        };
    }
}

Remarks

Use this parser when callers should be able to request a version by a shortened or compatibility-oriented token, while the application still works with the canonical Asp.Versioning.ApiVersion instance. Alias matching is performed before the fallback parser is invoked.

Constructors

ApiVersionAliasParser(IReadOnlyDictionary<string, ApiVersion>)

Initializes a new instance of the ApiVersionAliasParser class that falls back to Asp.Versioning.ApiVersionParser.Default.

public ApiVersionAliasParser(IReadOnlyDictionary<string, ApiVersion> aliases)

Parameters

aliases IReadOnlyDictionary<string, ApiVersion>

The alias map to use before invoking the default parser.

Remarks

The dictionary key is the external version token accepted from a request, and the dictionary value is the canonical Asp.Versioning.ApiVersion returned for that token.

Exceptions

ArgumentNullException

aliases is null.

ArgumentException

aliases contains no entries.

ApiVersionAliasParser(IReadOnlyDictionary<string, ApiVersion>, IApiVersionParser)

Initializes a new instance of the ApiVersionAliasParser class with the specified alias map and fallback parser.

public ApiVersionAliasParser(IReadOnlyDictionary<string, ApiVersion> aliases, IApiVersionParser fallback)

Parameters

aliases IReadOnlyDictionary<string, ApiVersion>

The alias map to use before invoking fallback.

fallback IApiVersionParser

The parser to use when aliases does not contain the requested version token.

Remarks

The dictionary key is the external version token accepted from a request, and the dictionary value is the canonical Asp.Versioning.ApiVersion returned for that token. Alias lookup uses the comparer configured by the supplied aliases dictionary.

Exceptions

ArgumentNullException

aliases or fallback is null.

ArgumentException

aliases contains no entries.

Methods

CreateSemanticVersionAlias(SemanticApiVersion)

Creates an API version parser that recognizes shortened aliases for a single semantic API version.

public static IApiVersionParser CreateSemanticVersionAlias(SemanticApiVersion version)

Parameters

version SemanticApiVersion

The semantic API version to expose through major, major-minor, and major-minor-patch aliases.

Returns

IApiVersionParser

An Asp.Versioning.IApiVersionParser that maps aliases such as 1, 1.2, and 1.2.3 to the specified version.

Remarks

The returned parser falls back to Asp.Versioning.ApiVersionParser.Default when a requested version is not one of the generated aliases.

CreateSemanticVersionAlias(IEnumerable<SemanticApiVersion>)

Creates an API version parser that recognizes shortened aliases for the specified semantic API versions.

public static IApiVersionParser CreateSemanticVersionAlias(IEnumerable<SemanticApiVersion> versions)

Parameters

versions IEnumerable<SemanticApiVersion>

The semantic API versions to expose through major, major-minor, and major-minor-patch aliases.

Returns

IApiVersionParser

An Asp.Versioning.IApiVersionParser that maps each generated alias to its corresponding SemanticApiVersion.

Remarks

For each supplied version, aliases are generated from Asp.Versioning.ApiVersion.MajorVersion, Asp.Versioning.ApiVersion.MinorVersion, and PatchVersion. If duplicate aliases are produced, the first version that contributed the alias is retained. The returned parser falls back to Asp.Versioning.ApiVersionParser.Default when a requested version is not one of the generated aliases.

Parse(ReadOnlySpan<char>)

Parses the specified text into an API version by resolving aliases before using the fallback parser.

public ApiVersion Parse(ReadOnlySpan<char> text)

Parameters

text ReadOnlySpan<char>

The API version text to parse.

Returns

ApiVersion

The API version that matched either an alias or the fallback parser.

Exceptions

FormatException

text is neither a known alias nor a version accepted by the fallback parser.

TryParse(ReadOnlySpan<char>, out ApiVersion)

Tries to parse the specified text into an API version by resolving aliases before using the fallback parser.

public virtual bool TryParse(ReadOnlySpan<char> text, out ApiVersion apiVersion)

Parameters

text ReadOnlySpan<char>

The API version text to parse.

apiVersion ApiVersion

When this method returns, contains the API version that matched either an alias or the fallback parser; otherwise, contains null.

Returns

bool

true if text matched an alias or was accepted by the fallback parser; otherwise, false.

Remarks

Override this method to customize alias resolution while preserving the same parse contract.

See Also

IApiVersionParser