Class ServiceCollectionExtensions

Namespace

Codebelt.Extensions.Asp.Versioning

Assembly

Codebelt.Extensions.Asp.Versioning.dll

Extension methods for the IServiceCollection interface.

public static class ServiceCollectionExtensions

Inheritance

object

ServiceCollectionExtensions

Examples

Call AddRestfulApiVersioning on IServiceCollection to wire up Asp.Versioning for a RESTful API in a single registration. The extension combines AddApiVersioning, AddMvc, and AddApiExplorer, installs RestfulApiVersionReader to parse the version from a filtered set of Accept media types, and registers problem-details integration that translates version-resolution errors into HttpStatusCodeException values compatible with the rest of the pipeline. When the application also needs short version tokens such as 1 or 1.2 to map to canonical SemanticApiVersion values, follow up with AddApiVersionParser and an ApiVersionAliasParser built from the same set of versions. Configure the default version, parameter name, accepted media types, version selector strategy, and problem-details style through the optional setup delegate.

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

namespace Codebelt.Extensions.Asp.Versioning;

public class RestfulApiVersioningServiceRegistration
{
    public static void ConfigureServices(IServiceCollection services)
    {
        var stable = new SemanticApiVersion(1, 0, 0);
        var next = new SemanticApiVersion(2, 0, 0);

        services.AddRestfulApiVersioning(options =>
        {
            options.DefaultApiVersion = stable;
            options.ParameterName = "version";
            options.ReportApiVersions = true;
            options.UseApiVersionSelector<LowestImplementedApiVersionSelector>();
        });

        services.AddApiVersionParser(ApiVersionAliasParser.CreateSemanticVersionAlias([stable, next]));
    }
}

Methods

AddApiVersionParser<T>(IServiceCollection, T)

Adds the specified API version parser as the singleton parser used by API versioning services.

public static IServiceCollection AddApiVersionParser<T>(this IServiceCollection services, T parser) where T : IApiVersionParser

Parameters

services IServiceCollection

The IServiceCollection to extend.

parser T

The parser instance that should resolve API version values for the application.

Returns

IServiceCollection

A reference to services so that additional calls can be chained.

Type Parameters

T

The concrete Asp.Versioning.IApiVersionParser type to register.

Remarks

Register a custom parser when the application accepts version formats that differ from the default parser, such as semantic version aliases or compatibility tokens. The supplied parser is registered as the Asp.Versioning.IApiVersionParser singleton.

Exceptions

ArgumentNullException

services or parser is null.

AddRestfulApiVersioning(IServiceCollection, Action<RestfulApiVersioningOptions>)

Adds a compound service API versioning to the specified services collection that is optimized for RESTful APIs.

public static IServiceCollection AddRestfulApiVersioning(this IServiceCollection services, Action<RestfulApiVersioningOptions> setup = null)

Parameters

services IServiceCollection

The IServiceCollection to extend.

setup Action<RestfulApiVersioningOptions>

The RestfulApiVersioningOptions that may be configured.

Returns

IServiceCollection

A reference to services so that additional calls can be chained.

Remarks

This is a convenient method to add API versioning to your ASP.NET Core WebApi. Call AddApiVersioning, AddMvc and AddApiExplorer. Configuration, which is optimized for RESTful APIs, are done through setup. When DefaultApiVersion is a SemanticApiVersion, semantic aliases are automatically registered only for that default version. Applications that expose additional semantic versions and need aliases such as 2 or 2.0 should call AddApiVersionParser<T>(IServiceCollection, T) with CreateSemanticVersionAlias(IEnumerable<SemanticApiVersion>).