[release/7.0-rc1] Add support for running final conventions during build (#43225)

* Add support for running final conventions during build

* Fix typo and use stack for backing store

* Update application order and address feedback

- Fix ordering of group and entry-specific conventions in parameter list
- Update to use FIFO ordering within finally conventions of the same level
- Add tests for WithOpenApi on group and endpoint
- Revert to using List instead of Stack for convention
- Fix ordering of outer and inner group in RouteGroups

* Add new test

* Update tests

Author: captainsafia

src/Components/Server/src/Builder/ComponentEndpointConventionBuilder.cs

@@ -29,4 +29,12 @@ public void Add(Action<EndpointBuilder> convention)
         _disconnectEndpoint.Add(convention);
         _jsInitializersEndpoint.Add(convention);
     }
+
+    /// <inheritdoc/>
+    public void Finally(Action<EndpointBuilder> finalConvention)
+    {
+        _hubEndpoint.Finally(finalConvention);
+        _disconnectEndpoint.Finally(finalConvention);
+        _jsInitializersEndpoint.Finally(finalConvention);
+    }
 }

src/Components/Server/src/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.AspNetCore.Builder.ComponentEndpointConventionBuilder.Finally(System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>! finalConvention) -> void

src/Components/Server/test/ComponentEndpointRouteBuilderExtensionsTest.cs

@@ -4,6 +4,7 @@
 using System.Diagnostics;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.FileProviders;
@@ -52,6 +53,75 @@ public void MapBlazorHub_MostGeneralOverload_MapsUnderlyingHub()
         Assert.True(called);
     }
 
+    [Fact]
+    public void MapBlazorHub_AppliesFinalConventionToEachBuilder()
+    {
+        // Arrange
+        var applicationBuilder = CreateAppBuilder();
+        var buildersAffected = new List<string>();
+        var called = false;
+
+        // Act
+        var app = applicationBuilder
+            .UseRouting()
+            .UseEndpoints(endpoints =>
+            {
+                endpoints
+                .MapBlazorHub(dispatchOptions => called = true)
+                .WithMetadata("initial-md")
+                .Finally(builder =>
+                {
+                    if (builder.Metadata.Any(md => md is string smd && smd == "initial-md"))
+                    {
+                        buildersAffected.Add(builder.DisplayName);
+                    }
+                });
+            }).Build();
+
+        // Trigger endpoint construction
+        app.Invoke(new DefaultHttpContext());
+
+        // Assert
+        Assert.True(called);
+        // Final conventions are applied to each of the builders
+        // in the Blazor component hub
+        Assert.Equal(4, buildersAffected.Count);
+        Assert.Contains("/_blazor/negotiate", buildersAffected);
+        Assert.Contains("/_blazor", buildersAffected);
+        Assert.Contains("Blazor disconnect", buildersAffected);
+        Assert.Contains("Blazor initializers", buildersAffected);
+    }
+
+    [Fact]
+    public void MapBlazorHub_AppliesFinalConventionsInFIFOOrder()
+    {
+        // Arrange
+        var applicationBuilder = CreateAppBuilder();
+        var called = false;
+        var populatedMetadata = Array.Empty<string>();
+
+        // Act
+        var app = applicationBuilder
+            .UseRouting()
+            .UseEndpoints(endpoints =>
+            {
+                var builder = endpoints.MapBlazorHub(dispatchOptions => called = true);
+                builder.Finally(b => b.Metadata.Add("first-in"));
+                builder.Finally(b => b.Metadata.Add("last-in"));
+                builder.Finally(b =>
+                {
+                    populatedMetadata = b.Metadata.OfType<string>().ToArray();
+                });
+            }).Build();
+
+        // Trigger endpoint construction
+        app.Invoke(new DefaultHttpContext());
+
+        // Assert
+        Assert.True(called);
+        Assert.Equal(new[] { "first-in", "last-in" }, populatedMetadata);
+    }
+
     private IApplicationBuilder CreateAppBuilder()
     {
         var environment = new Mock<IWebHostEnvironment>();

src/Http/Http.Abstractions/src/Extensions/IEndpointConventionBuilder.cs

@@ -16,4 +16,11 @@ public interface IEndpointConventionBuilder
     /// </summary>
     /// <param name="convention">The convention to add to the builder.</param>
     void Add(Action<EndpointBuilder> convention);
+
+    /// <summary>
+    /// Registers the specified convention for execution after conventions registered
+    /// via <see cref="Add(Action{EndpointBuilder})"/>
+    /// </summary>
+    /// <param name="finallyConvention">The convention to add to the builder.</param>
+    void Finally(Action<EndpointBuilder> finallyConvention) => throw new NotImplementedException();
 }

src/Http/Http.Abstractions/src/PublicAPI.Unshipped.txt

@@ -7,6 +7,7 @@ abstract Microsoft.AspNetCore.Http.EndpointFilterInvocationContext.HttpContext.g
 Microsoft.AspNetCore.Builder.EndpointBuilder.ApplicationServices.get -> System.IServiceProvider!
 Microsoft.AspNetCore.Builder.EndpointBuilder.ApplicationServices.set -> void
 Microsoft.AspNetCore.Builder.EndpointBuilder.FilterFactories.get -> System.Collections.Generic.IList<System.Func<Microsoft.AspNetCore.Http.EndpointFilterFactoryContext!, Microsoft.AspNetCore.Http.EndpointFilterDelegate!, Microsoft.AspNetCore.Http.EndpointFilterDelegate!>!>!
+Microsoft.AspNetCore.Builder.IEndpointConventionBuilder.Finally(System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>! finallyConvention) -> void
 Microsoft.AspNetCore.Http.AsParametersAttribute
 Microsoft.AspNetCore.Http.AsParametersAttribute.AsParametersAttribute() -> void
 Microsoft.AspNetCore.Http.CookieBuilder.Extensions.get -> System.Collections.Generic.IList<string!>!

src/Http/Routing/src/Builder/RouteHandlerBuilder.cs

@@ -12,15 +12,18 @@ public sealed class RouteHandlerBuilder : IEndpointConventionBuilder
 {
     private readonly IEnumerable<IEndpointConventionBuilder>? _endpointConventionBuilders;
     private readonly ICollection<Action<EndpointBuilder>>? _conventions;
+    private readonly ICollection<Action<EndpointBuilder>>? _finallyConventions;
 
     /// <summary>
     /// Instantiates a new <see cref="RouteHandlerBuilder" /> given a ThrowOnAddAfterEndpointBuiltConventionCollection from
     /// <see cref="RouteEndpointDataSource.AddRouteHandler(Routing.Patterns.RoutePattern, Delegate, IEnumerable{string}?, bool)"/>.
     /// </summary>
     /// <param name="conventions">The convention list returned from <see cref="RouteEndpointDataSource"/>.</param>
-    internal RouteHandlerBuilder(ICollection<Action<EndpointBuilder>> conventions)
+    /// <param name="finallyConventions">The final convention list returned from <see cref="RouteEndpointDataSource"/>.</param>
+    internal RouteHandlerBuilder(ICollection<Action<EndpointBuilder>> conventions, ICollection<Action<EndpointBuilder>> finallyConventions)
     {
         _conventions = conventions;
+        _finallyConventions = finallyConventions;
     }
 
     /// <summary>
@@ -51,4 +54,20 @@ public void Add(Action<EndpointBuilder> convention)
             }
         }
     }
+
+    /// <inheritdoc />
+    public void Finally(Action<EndpointBuilder> finalConvention)
+    {
+        if (_finallyConventions is not null)
+        {
+            _finallyConventions.Add(finalConvention);
+        }
+        else
+        {
+            foreach (var endpointConventionBuilder in _endpointConventionBuilders!)
+            {
+                endpointConventionBuilder.Finally(finalConvention);
+            }
+        }
+    }
 }

src/Http/Routing/src/DefaultEndpointConventionBuilder.cs

@@ -73,6 +73,11 @@ public virtual IReadOnlyList<Endpoint> GetGroupedEndpoints(RouteGroupContext con
                 routeEndpointBuilder.Metadata.Add(metadata);
             }
 
+            foreach (var finallyConvention in context.FinallyConventions)
+            {
+                finallyConvention(routeEndpointBuilder);
+            }
+
             // The RoutePattern, RequestDelegate, Order and DisplayName can all be overridden by non-group-aware conventions.
             // Unlike with metadata, if a convention is applied to a group that changes any of these, I would expect these
             // to be overridden as there's no reasonable way to merge these properties.

src/Http/Routing/src/EndpointDataSource.cs

@@ -1,14 +1,20 @@
 #nullable enable
+Microsoft.AspNetCore.Builder.RouteHandlerBuilder.Finally(System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>! finalConvention) -> void
 Microsoft.AspNetCore.Http.EndpointFilterExtensions
 Microsoft.AspNetCore.Routing.CompositeEndpointDataSource.Dispose() -> void
 Microsoft.AspNetCore.Routing.HttpMethodMetadata.AcceptCorsPreflight.set -> void
 Microsoft.AspNetCore.Routing.IHttpMethodMetadata.AcceptCorsPreflight.set -> void
 Microsoft.AspNetCore.Routing.RouteGroupBuilder
 Microsoft.AspNetCore.Routing.RouteGroupContext
 Microsoft.AspNetCore.Routing.RouteGroupContext.ApplicationServices.get -> System.IServiceProvider!
+Microsoft.AspNetCore.Routing.RouteGroupContext.ApplicationServices.init -> void
 Microsoft.AspNetCore.Routing.RouteGroupContext.Conventions.get -> System.Collections.Generic.IReadOnlyList<System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>!>!
+Microsoft.AspNetCore.Routing.RouteGroupContext.Conventions.init -> void
+Microsoft.AspNetCore.Routing.RouteGroupContext.FinallyConventions.get -> System.Collections.Generic.IReadOnlyList<System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>!>!
+Microsoft.AspNetCore.Routing.RouteGroupContext.FinallyConventions.init -> void
 Microsoft.AspNetCore.Routing.RouteGroupContext.Prefix.get -> Microsoft.AspNetCore.Routing.Patterns.RoutePattern!
-Microsoft.AspNetCore.Routing.RouteGroupContext.RouteGroupContext(Microsoft.AspNetCore.Routing.Patterns.RoutePattern! prefix, System.Collections.Generic.IReadOnlyList<System.Action<Microsoft.AspNetCore.Builder.EndpointBuilder!>!>! conventions, System.IServiceProvider! applicationServices) -> void
+Microsoft.AspNetCore.Routing.RouteGroupContext.Prefix.init -> void
+Microsoft.AspNetCore.Routing.RouteGroupContext.RouteGroupContext() -> void
 Microsoft.AspNetCore.Routing.RouteOptions.SetParameterPolicy(string! token, System.Type! type) -> void
 Microsoft.AspNetCore.Routing.RouteOptions.SetParameterPolicy<T>(string! token) -> void
 override Microsoft.AspNetCore.Routing.CompositeEndpointDataSource.GetGroupedEndpoints(Microsoft.AspNetCore.Routing.RouteGroupContext! context) -> System.Collections.Generic.IReadOnlyList<Microsoft.AspNetCore.Http.Endpoint!>!

src/Http/Routing/src/PublicAPI.Unshipped.txt

@@ -31,6 +31,7 @@ public RouteHandlerBuilder AddRequestDelegate(
     {
 
         var conventions = new ThrowOnAddAfterEndpointBuiltConventionCollection();
+        var finallyConventions = new ThrowOnAddAfterEndpointBuiltConventionCollection();
 
         _routeEntries.Add(new()
         {
@@ -39,9 +40,10 @@ public RouteHandlerBuilder AddRequestDelegate(
             HttpMethods = httpMethods,
             RouteAttributes = RouteAttributes.None,
             Conventions = conventions,
+            FinallyConventions = finallyConventions
         });
 
-        return new RouteHandlerBuilder(conventions);
+        return new RouteHandlerBuilder(conventions, finallyConventions);
     }
 
     public RouteHandlerBuilder AddRouteHandler(
@@ -51,6 +53,7 @@ public RouteHandlerBuilder AddRouteHandler(
         bool isFallback)
     {
         var conventions = new ThrowOnAddAfterEndpointBuiltConventionCollection();
+        var finallyConventions = new ThrowOnAddAfterEndpointBuiltConventionCollection();
 
         var routeAttributes = RouteAttributes.RouteHandler;
         if (isFallback)
@@ -65,9 +68,10 @@ public RouteHandlerBuilder AddRouteHandler(
             HttpMethods = httpMethods,
             RouteAttributes = routeAttributes,
             Conventions = conventions,
+            FinallyConventions = finallyConventions
         });
 
-        return new RouteHandlerBuilder(conventions);
+        return new RouteHandlerBuilder(conventions, finallyConventions);
     }
 
     public override IReadOnlyList<RouteEndpoint> Endpoints
@@ -88,7 +92,7 @@ public override IReadOnlyList<RouteEndpoint> GetGroupedEndpoints(RouteGroupConte
         var endpoints = new RouteEndpoint[_routeEntries.Count];
         for (int i = 0; i < _routeEntries.Count; i++)
         {
-            endpoints[i] = (RouteEndpoint)CreateRouteEndpointBuilder(_routeEntries[i], context.Prefix, context.Conventions).Build();
+            endpoints[i] = (RouteEndpoint)CreateRouteEndpointBuilder(_routeEntries[i], context.Prefix, context.Conventions, context.FinallyConventions).Build();
         }
         return endpoints;
     }
@@ -109,7 +113,7 @@ internal RouteEndpointBuilder GetSingleRouteEndpointBuilder()
     [UnconditionalSuppressMessage("Trimmer", "IL2026",
         Justification = "We surface a RequireUnreferencedCode in the call to the Map method adding this EndpointDataSource. The trimmer is unable to infer this.")]
     private RouteEndpointBuilder CreateRouteEndpointBuilder(
-        RouteEntry entry, RoutePattern? groupPrefix = null, IReadOnlyList<Action<EndpointBuilder>>? groupConventions = null)
+        RouteEntry entry, RoutePattern? groupPrefix = null, IReadOnlyList<Action<EndpointBuilder>>? groupConventions = null, IReadOnlyList<Action<EndpointBuilder>>? groupFinallyConventions = null)
     {
         var pattern = RoutePatternFactory.Combine(groupPrefix, entry.RoutePattern);
         var handler = entry.RouteHandler;
@@ -190,7 +194,7 @@ private RouteEndpointBuilder CreateRouteEndpointBuilder(
             }
         }
 
-        entry.Conventions.IsReadonly = true;
+        entry.Conventions.IsReadOnly = true;
         foreach (var entrySpecificConvention in entry.Conventions)
         {
             entrySpecificConvention(builder);
@@ -225,6 +229,22 @@ private RouteEndpointBuilder CreateRouteEndpointBuilder(
             builder.RequestDelegate = factoryCreatedRequestDelegate;
         }
 
+        entry.FinallyConventions.IsReadOnly = true;
+        foreach (var entryFinallyConvention in entry.FinallyConventions)
+        {
+            entryFinallyConvention(builder);
+        }
+
+        if (groupFinallyConventions is not null)
+        {
+            // Group conventions are ordered by the RouteGroupBuilder before
+            // being provided here.
+            foreach (var groupFinallyConvention in groupFinallyConventions)
+            {
+                groupFinallyConvention(builder);
+            }
+        }
+
         return builder;
     }
 
@@ -265,6 +285,7 @@ private struct RouteEntry
         public IEnumerable<string>? HttpMethods { get; init; }
         public RouteAttributes RouteAttributes { get; init; }
         public ThrowOnAddAfterEndpointBuiltConventionCollection Conventions { get; init; }
+        public ThrowOnAddAfterEndpointBuiltConventionCollection FinallyConventions { get; init; }
     }
 
     [Flags]
@@ -283,11 +304,11 @@ private sealed class ThrowOnAddAfterEndpointBuiltConventionCollection : List<Act
     {
         // We throw if someone tries to add conventions to the RouteEntry after endpoints have already been resolved meaning the conventions
         // will not be observed given RouteEndpointDataSource is not meant to be dynamic and uses NullChangeToken.Singleton.
-        public bool IsReadonly { get; set; }
+        public bool IsReadOnly { get; set; }
 
         void ICollection<Action<EndpointBuilder>>.Add(Action<EndpointBuilder> convention)
         {
-            if (IsReadonly)
+            if (IsReadOnly)
             {
                 throw new InvalidOperationException(Resources.RouteEndpointDataSource_ConventionsCannotBeModifiedAfterBuild);
             }