Refactor to support API version metadata collation via DI. Fixes #922

Author: commonsensesoftware

src/AspNetCore/OData/src/Asp.Versioning.OData/Routing/DefaultMetadataMatcherPolicy.cs

@@ -3,6 +3,7 @@
 namespace Asp.Versioning.Routing;
 
 using Asp.Versioning;
+using Asp.Versioning.ApiExplorer;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.OData.Routing;
 using Microsoft.AspNetCore.OData.Routing.Template;
@@ -159,6 +160,7 @@ public PolicyJumpTable BuildJumpTable( int exitDestination, IReadOnlyList<Policy
     private static int ApiVersioningPolicy() =>
         new ApiVersionMatcherPolicy(
             ApiVersionParser.Default,
+            Enumerable.Empty<IApiVersionMetadataCollationProvider>(),
             Options.Create( new ApiVersioningOptions() ),
             new NullLogger<ApiVersionMatcherPolicy>() ).Order;
 

src/AspNetCore/WebApi/src/Asp.Versioning.Http/ApiExplorer/ApiVersionMetadataCollationCollection.cs

@@ -0,0 +1,135 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+using System.Collections;
+
+/// <summary>
+/// Represents a collection of collated API version metadata.
+/// </summary>
+public class ApiVersionMetadataCollationCollection : IList<ApiVersionMetadata>, IReadOnlyList<ApiVersionMetadata>
+{
+    private readonly List<ApiVersionMetadata> items;
+    private readonly List<string?> groups;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ApiVersionMetadataCollationCollection"/> class.
+    /// </summary>
+    public ApiVersionMetadataCollationCollection()
+    {
+        items = new();
+        groups = new();
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ApiVersionMetadataCollationCollection"/> class.
+    /// </summary>
+    /// <param name="capacity">The initial capacity of the collection.</param>
+    public ApiVersionMetadataCollationCollection( int capacity )
+    {
+        items = new( capacity );
+        groups = new( capacity );
+    }
+
+    /// <summary>
+    /// Gets the item in the list at the specified index.
+    /// </summary>
+    /// <param name="index">The zero-based index of the item to retrieve.</param>
+    /// <returns>The item at the specified index.</returns>
+    public ApiVersionMetadata this[int index] => items[index];
+
+    ApiVersionMetadata IList<ApiVersionMetadata>.this[int index]
+    {
+        get => items[index];
+        set => throw new NotSupportedException();
+    }
+
+    /// <inheritdoc />
+    public int Count => items.Count;
+
+#pragma warning disable CA1033 // Interface methods should be callable by child types
+    bool ICollection<ApiVersionMetadata>.IsReadOnly => ( (ICollection<ApiVersionMetadata>) items ).IsReadOnly;
+#pragma warning restore CA1033 // Interface methods should be callable by child types
+
+    /// <inheritdoc />
+    public void Add( ApiVersionMetadata item ) => Insert( Count, item, default );
+
+    /// <summary>
+    /// Adds an item to the collection.
+    /// </summary>
+    /// <param name="item">The item to add.</param>
+    /// <param name="groupName">The associated group name, if any.</param>
+    public void Add( ApiVersionMetadata item, string? groupName ) => Insert( Count, item, groupName );
+
+    /// <inheritdoc />
+    public void Clear()
+    {
+        items.Clear();
+        groups.Clear();
+    }
+
+    /// <inheritdoc />
+    public bool Contains( ApiVersionMetadata item ) => item != null && items.Contains( item );
+
+    /// <inheritdoc />
+    public void CopyTo( ApiVersionMetadata[] array, int arrayIndex ) => items.CopyTo( array, arrayIndex );
+
+    /// <inheritdoc />
+    public IEnumerator<ApiVersionMetadata> GetEnumerator() => items.GetEnumerator();
+
+    /// <inheritdoc />
+    public int IndexOf( ApiVersionMetadata item ) => item == null ? -1 : items.IndexOf( item );
+
+    /// <inheritdoc />
+    public void Insert( int index, ApiVersionMetadata item ) => Insert( index, item, default );
+
+    /// <summary>
+    /// Inserts an item into the collection.
+    /// </summary>
+    /// <param name="index">The zero-based index where insertion takes place.</param>
+    /// <param name="item">The item to insert.</param>
+    /// <param name="groupName">The associated group name, if any.</param>
+    public void Insert( int index, ApiVersionMetadata item, string? groupName )
+    {
+        items.Insert( index, item ?? throw new ArgumentNullException( nameof( item ) ) );
+        groups.Insert( index, groupName );
+    }
+
+    /// <inheritdoc />
+    public bool Remove( ApiVersionMetadata item )
+    {
+        if ( item == null )
+        {
+            return false;
+        }
+
+        var index = items.IndexOf( item );
+
+        if ( index < 0 )
+        {
+            return false;
+        }
+
+        RemoveAt( index );
+        return true;
+    }
+
+    /// <inheritdoc />
+    public void RemoveAt( int index )
+    {
+        items.RemoveAt( index );
+        groups.RemoveAt( index );
+    }
+
+    IEnumerator IEnumerable.GetEnumerator() => ( (IEnumerable) items ).GetEnumerator();
+
+    /// <summary>
+    /// Gets the group name for the item at the specified index.
+    /// </summary>
+    /// <param name="index">The zero-based index of the item to get the group name for.</param>
+    /// <returns>The associated group name or <c>null</c>.</returns>
+    /// <remarks>If the specified <paramref name="index"/> is out of range, <c>null</c>
+    /// is returned.</remarks>
+    public string? GroupName( int index ) =>
+        index < 0 || index >= groups.Count ? default : groups[index];
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Http/ApiExplorer/ApiVersionMetadataCollationContext.cs

@@ -0,0 +1,15 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+/// <summary>
+/// Represents the context used during API version metadata collation.
+/// </summary>
+public class ApiVersionMetadataCollationContext
+{
+    /// <summary>
+    /// Gets the read-only list of collation results.
+    /// </summary>
+    /// <value>The <see cref="IReadOnlyList{T}">read-only list</see> of collation results.</value>
+    public ApiVersionMetadataCollationCollection Results { get; } = new();
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Http/ApiExplorer/EndpointApiVersionMetadataCollationProvider.cs

@@ -0,0 +1,53 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.Primitives;
+
+/// <summary>
+/// Represents the API version metadata collection provider for endpoints.
+/// </summary>
+[CLSCompliant( false )]
+public sealed class EndpointApiVersionMetadataCollationProvider : IApiVersionMetadataCollationProvider
+{
+    private readonly EndpointDataSource endpointDataSource;
+    private int version;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EndpointApiVersionMetadataCollationProvider"/> class.
+    /// </summary>
+    /// <param name="endpointDataSource">The underlying <see cref="endpointDataSource">endpoint data source</see>.</param>
+    public EndpointApiVersionMetadataCollationProvider( EndpointDataSource endpointDataSource )
+    {
+        this.endpointDataSource = endpointDataSource ?? throw new ArgumentNullException( nameof( endpointDataSource ) );
+        ChangeToken.OnChange( endpointDataSource.GetChangeToken, () => ++version );
+    }
+
+    /// <inheritdoc />
+    public int Version => version;
+
+    /// <inheritdoc />
+    public void Execute( ApiVersionMetadataCollationContext context )
+    {
+        if ( context == null )
+        {
+            throw new ArgumentNullException( nameof( context ) );
+        }
+
+        var endpoints = endpointDataSource.Endpoints;
+
+        for ( var i = 0; i < endpoints.Count; i++ )
+        {
+            var endpoint = endpoints[i];
+
+            if ( endpoint.Metadata.GetMetadata<ApiVersionMetadata>() is not ApiVersionMetadata item )
+            {
+                continue;
+            }
+
+            var groupName = endpoint.Metadata.OfType<IEndpointGroupNameMetadata>().LastOrDefault()?.EndpointGroupName;
+            context.Results.Add( item, groupName );
+        }
+    }
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Http/ApiExplorer/IApiVersionMetadataCollationProvider.cs

@@ -0,0 +1,21 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+
+namespace Asp.Versioning.ApiExplorer;
+
+/// <summary>
+/// Defines the behavior of an API version metadata collation provider.
+/// </summary>
+public interface IApiVersionMetadataCollationProvider
+{
+    /// <summary>
+    /// Gets version of the underlying provider results.
+    /// </summary>
+    /// <value>The version of the provider results. This can be used to detect changes.</value>
+    int Version { get; }
+
+    /// <summary>
+    /// Executes the provider using the given context.
+    /// </summary>
+    /// <param name="context">The collation context.</param>
+    void Execute( ApiVersionMetadataCollationContext context );
+}

src/AspNetCore/WebApi/src/Asp.Versioning.Http/DependencyInjection/IServiceCollectionExtensions.cs

@@ -3,7 +3,7 @@
 namespace Microsoft.Extensions.DependencyInjection;
 
 using Asp.Versioning;
-using Asp.Versioning.Builder;
+using Asp.Versioning.ApiExplorer;
 using Asp.Versioning.Routing;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
@@ -92,6 +92,7 @@ private static void AddApiVersioningServices( IServiceCollection services )
         services.TryAddSingleton<ISunsetPolicyManager, SunsetPolicyManager>();
         services.TryAddEnumerable( Transient<IPostConfigureOptions<RouteOptions>, ApiVersioningRouteOptionsSetup>() );
         services.TryAddEnumerable( Singleton<MatcherPolicy, ApiVersionMatcherPolicy>() );
+        services.TryAddEnumerable( Singleton<IApiVersionMetadataCollationProvider, EndpointApiVersionMetadataCollationProvider>() );
         services.Replace( WithLinkGeneratorDecorator( services ) );
         TryAddProblemDetailsRfc7231Compliance( services );
     }
@@ -157,6 +158,8 @@ LinkGenerator NewFactory( IServiceProvider serviceProvider )
         }
     }
 
+    // TODO: Remove in .NET 8.0
+    // REF: https://github.com/dotnet/aspnetcore/issues/45051
     private static void TryAddProblemDetailsRfc7231Compliance( IServiceCollection services )
     {
         var descriptor = services.FirstOrDefault( IsDefaultProblemDetailsWriter );