Implement IEndpointMetadataProvider & IEndpointParameterMetadataProvider (#40926)

Fixes #40646

Author: DamianEdwards

src/Http/Http.Extensions/src/EndpointMetadataContext.cs

@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Reflection;
+
+namespace Microsoft.AspNetCore.Http.Metadata;
+
+/// <summary>
+/// Represents the information accessible during endpoint creation by types that implement <see cref="IEndpointMetadataProvider"/>.
+/// </summary>
+public sealed class EndpointMetadataContext
+{
+    /// <summary>
+    /// Gets the <see cref="MethodInfo"/> associated with the current route handler.
+    /// </summary>
+    public MethodInfo Method { get; init; } = null!; // Is initialized when created by RequestDelegateFactory
+
+    /// <summary>
+    /// Gets the <see cref="IServiceProvider"/> instance used to access application services.
+    /// </summary>
+    public IServiceProvider? Services { get; init; }
+
+    /// <summary>
+    /// Gets the list of objects that will be added to the metadata of the endpoint.
+    /// </summary>
+    public IList<object> EndpointMetadata { get; init; } = null!; // Is initialized when created by RequestDelegateFactory
+}

src/Http/Http.Extensions/src/EndpointParameterMetadataContext.cs

@@ -0,0 +1,27 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Reflection;
+
+namespace Microsoft.AspNetCore.Http.Metadata;
+
+/// <summary>
+/// Represents the information accessible during endpoint creation by types that implement <see cref="IEndpointParameterMetadataProvider"/>.
+/// </summary>
+public sealed class EndpointParameterMetadataContext
+{
+    /// <summary>
+    /// Gets the parameter of the route handler delegate of the endpoint being created.
+    /// </summary>
+    public ParameterInfo Parameter { get; init; } = null!; // Is initialized when created by RequestDelegateFactory
+
+    /// <summary>
+    /// Gets the <see cref="MethodInfo"/> associated with the current route handler.
+    /// </summary>
+    public IServiceProvider? Services { get; init; }
+
+    /// <summary>
+    /// Gets the list of objects that will be added to the metadata of the endpoint.
+    /// </summary>
+    public IList<object> EndpointMetadata { get; init; } = null!; // Is initialized when created by RequestDelegateFactory
+}

src/Http/Http.Extensions/src/IEndpointMetadataProvider.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Http.Metadata;
+
+/// <summary>
+/// Indicates that a type provides a static method that provides <see cref="Endpoint"/> metadata when declared as a parameter type or the
+/// returned type of an <see cref="Endpoint"/> route handler delegate.
+/// </summary>
+public interface IEndpointMetadataProvider
+{
+    /// <summary>
+    /// Populates metadata for the related <see cref="Endpoint"/>.
+    /// </summary>
+    /// <remarks>
+    /// This method is called by <see cref="RequestDelegateFactory"/> when creating a <see cref="RequestDelegate"/>.
+    /// The <see cref="EndpointMetadataContext.EndpointMetadata"/> property of <paramref name="context"/> will contain
+    /// the initial metadata for the endpoint.<br />
+    /// Add or remove objects on <see cref="EndpointMetadataContext.EndpointMetadata"/> to affect the metadata of the endpoint.
+    /// </remarks>
+    /// <param name="context">The <see cref="EndpointMetadataContext"/>.</param>
+    static abstract void PopulateMetadata(EndpointMetadataContext context);
+}

src/Http/Http.Extensions/src/IEndpointParameterMetadataProvider.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.Http.Metadata;
+
+/// <summary>
+/// Indicates that a type provides a static method that provides <see cref="Endpoint"/> metadata when declared as the
+/// parameter type of an <see cref="Endpoint"/> route handler delegate.
+/// </summary>
+public interface IEndpointParameterMetadataProvider
+{
+    /// <summary>
+    /// Populates metadata for the related <see cref="Endpoint"/>.
+    /// </summary>
+    /// <remarks>
+    /// This method is called by <see cref="RequestDelegateFactory"/> when creating a <see cref="RequestDelegate"/>.
+    /// The <see cref="EndpointParameterMetadataContext.EndpointMetadata"/> property of <paramref name="parameterContext"/> will contain
+    /// the initial metadata for the endpoint.<br />
+    /// Add or remove objects on <see cref="EndpointParameterMetadataContext.EndpointMetadata"/> to affect the metadata of the endpoint.
+    /// </remarks>
+    /// <param name="parameterContext">The <see cref="EndpointParameterMetadataContext"/>.</param>
+    static abstract void PopulateMetadata(EndpointParameterMetadataContext parameterContext);
+}

src/Http/Http.Extensions/src/PublicAPI.Unshipped.txt

@@ -1,4 +1,26 @@
 #nullable enable
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.EndpointMetadata.get -> System.Collections.Generic.IList<object!>!
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.EndpointMetadata.init -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.EndpointMetadataContext() -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.Method.get -> System.Reflection.MethodInfo!
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.Method.init -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.Services.get -> System.IServiceProvider?
+Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext.Services.init -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.EndpointMetadata.get -> System.Collections.Generic.IList<object!>!
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.EndpointMetadata.init -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.EndpointParameterMetadataContext() -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.Parameter.get -> System.Reflection.ParameterInfo!
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.Parameter.init -> void
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.Services.get -> System.IServiceProvider?
+Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext.Services.init -> void
+Microsoft.AspNetCore.Http.Metadata.IEndpointMetadataProvider
+Microsoft.AspNetCore.Http.Metadata.IEndpointMetadataProvider.PopulateMetadata(Microsoft.AspNetCore.Http.Metadata.EndpointMetadataContext! context) -> void
+Microsoft.AspNetCore.Http.Metadata.IEndpointParameterMetadataProvider
+Microsoft.AspNetCore.Http.Metadata.IEndpointParameterMetadataProvider.PopulateMetadata(Microsoft.AspNetCore.Http.Metadata.EndpointParameterMetadataContext! parameterContext) -> void
+Microsoft.AspNetCore.Http.RequestDelegateFactoryOptions.InitialEndpointMetadata.get -> System.Collections.Generic.IEnumerable<object!>?
+Microsoft.AspNetCore.Http.RequestDelegateFactoryOptions.InitialEndpointMetadata.init -> void
 Microsoft.AspNetCore.Http.RequestDelegateFactoryOptions.RouteHandlerFilterFactories.get -> System.Collections.Generic.IReadOnlyList<System.Func<Microsoft.AspNetCore.Http.RouteHandlerContext!, Microsoft.AspNetCore.Http.RouteHandlerFilterDelegate!, Microsoft.AspNetCore.Http.RouteHandlerFilterDelegate!>!>?
 Microsoft.AspNetCore.Http.RequestDelegateFactoryOptions.RouteHandlerFilterFactories.init -> void
 Microsoft.Extensions.DependencyInjection.RouteHandlerJsonServiceExtensions

src/Http/Http.Extensions/src/RequestDelegateFactory.cs

@@ -47,6 +47,8 @@ public static partial class RequestDelegateFactory
     private static readonly MethodInfo StringResultWriteResponseAsyncMethod = typeof(RequestDelegateFactory).GetMethod(nameof(ExecuteWriteStringResponseAsync), BindingFlags.NonPublic | BindingFlags.Static)!;
     private static readonly MethodInfo StringIsNullOrEmptyMethod = typeof(string).GetMethod(nameof(string.IsNullOrEmpty), BindingFlags.Static | BindingFlags.Public)!;
     private static readonly MethodInfo WrapObjectAsValueTaskMethod = typeof(RequestDelegateFactory).GetMethod(nameof(WrapObjectAsValueTask), BindingFlags.NonPublic | BindingFlags.Static)!;
+    private static readonly MethodInfo PopulateMetadataForParameterMethod = typeof(RequestDelegateFactory).GetMethod(nameof(PopulateMetadataForParameter), BindingFlags.NonPublic | BindingFlags.Static)!;
+    private static readonly MethodInfo PopulateMetadataForEndpointMethod = typeof(RequestDelegateFactory).GetMethod(nameof(PopulateMetadataForEndpoint), BindingFlags.NonPublic | BindingFlags.Static)!;
 
     // Call WriteAsJsonAsync<object?>() to serialize the runtime return type rather than the declared return type.
     // https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-polymorphism
@@ -165,16 +167,26 @@ public static RequestDelegateResult Create(MethodInfo methodInfo, Func<HttpConte
         return new RequestDelegateResult(httpContext => targetableRequestDelegate(targetFactory(httpContext), httpContext), factoryContext.Metadata);
     }
 
-    private static FactoryContext CreateFactoryContext(RequestDelegateFactoryOptions? options) =>
-        new()
+    private static FactoryContext CreateFactoryContext(RequestDelegateFactoryOptions? options)
+    {
+        var context = new FactoryContext
         {
+            ServiceProvider = options?.ServiceProvider,
             ServiceProviderIsService = options?.ServiceProvider?.GetService<IServiceProviderIsService>(),
             RouteParameters = options?.RouteParameterNames?.ToList(),
             ThrowOnBadRequest = options?.ThrowOnBadRequest ?? false,
             DisableInferredFromBody = options?.DisableInferBodyFromParameters ?? false,
             Filters = options?.RouteHandlerFilterFactories?.ToList()
         };
 
+        if (options?.InitialEndpointMetadata is not null)
+        {
+            context.Metadata.AddRange(options.InitialEndpointMetadata);
+        }
+
+        return context;
+    }
+
     private static Func<object?, HttpContext, Task> CreateTargetableRequestDelegate(MethodInfo methodInfo, Expression? targetExpression, FactoryContext factoryContext)
     {
         // Non void return type
@@ -193,10 +205,20 @@ private static FactoryContext CreateFactoryContext(RequestDelegateFactoryOptions
         //     return default;
         // }
 
+        // Add MethodInfo as first metadata item
+        factoryContext.Metadata.Insert(0, methodInfo);
+
+        // CreateArguments will add metadata inferred from parameter details
         var arguments = CreateArguments(methodInfo.GetParameters(), factoryContext);
         var returnType = methodInfo.ReturnType;
         factoryContext.MethodCall = CreateMethodCall(methodInfo, targetExpression, arguments);
 
+        // Add metadata provided by the delegate return type and parameter types next, this will be more specific than inferred metadata from above
+        AddTypeProvidedMetadata(methodInfo, factoryContext.Metadata, factoryContext.ServiceProvider);
+
+        // Add method attributes as metadata *after* any inferred metadata so that the attributes hava a higher specificity
+        AddMethodAttributesAsMetadata(methodInfo, factoryContext.Metadata);
+
         // If there are filters registered on the route handler, then we update the method call and
         // return type associated with the request to allow for the filter invocation pipeline.
         if (factoryContext.Filters is { Count: > 0 })
@@ -261,6 +283,82 @@ target is null
         return filteredInvocation;
     }
 
+    private static void AddTypeProvidedMetadata(MethodInfo methodInfo, List<object> metadata, IServiceProvider? services)
+    {
+        object?[]? invokeArgs = null;
+
+        // Get metadata from parameter types
+        var parameters = methodInfo.GetParameters();
+        foreach (var parameter in parameters)
+        {
+            if (typeof(IEndpointParameterMetadataProvider).IsAssignableFrom(parameter.ParameterType))
+            {
+                // Parameter type implements IEndpointParameterMetadataProvider
+                var parameterContext = new EndpointParameterMetadataContext
+                {
+                    Parameter = parameter,
+                    EndpointMetadata = metadata,
+                    Services = services
+                };
+                invokeArgs ??= new object[1];
+                invokeArgs[0] = parameterContext;
+                PopulateMetadataForParameterMethod.MakeGenericMethod(parameter.ParameterType).Invoke(null, invokeArgs);
+            }
+
+            if (typeof(IEndpointMetadataProvider).IsAssignableFrom(parameter.ParameterType))
+            {
+                // Parameter type implements IEndpointMetadataProvider
+                var context = new EndpointMetadataContext
+                {
+                    Method = methodInfo,
+                    EndpointMetadata = metadata,
+                    Services = services
+                };
+                invokeArgs ??= new object[1];
+                invokeArgs[0] = context;
+                PopulateMetadataForEndpointMethod.MakeGenericMethod(parameter.ParameterType).Invoke(null, invokeArgs);
+            }
+        }
+
+        // Get metadata from return type
+        if (methodInfo.ReturnType is not null && typeof(IEndpointMetadataProvider).IsAssignableFrom(methodInfo.ReturnType))
+        {
+            // Return type implements IEndpointMetadataProvider
+            var context = new EndpointMetadataContext
+            {
+                Method = methodInfo,
+                EndpointMetadata = metadata,
+                Services = services
+            };
+            invokeArgs ??= new object[1];
+            invokeArgs[0] = context;
+            PopulateMetadataForEndpointMethod.MakeGenericMethod(methodInfo.ReturnType).Invoke(null, invokeArgs);
+        }
+    }
+
+    private static void PopulateMetadataForParameter<T>(EndpointParameterMetadataContext parameterContext)
+        where T : IEndpointParameterMetadataProvider
+    {
+        T.PopulateMetadata(parameterContext);
+    }
+
+    private static void PopulateMetadataForEndpoint<T>(EndpointMetadataContext context)
+        where T : IEndpointMetadataProvider
+    {
+        T.PopulateMetadata(context);
+    }
+
+    private static void AddMethodAttributesAsMetadata(MethodInfo methodInfo, List<object> metadata)
+    {
+        var attributes = methodInfo.GetCustomAttributes();
+
+        // This can be null if the delegate is a dynamic method or compiled from an expression tree
+        if (attributes is not null)
+        {
+            metadata.AddRange(attributes);
+        }
+    }
+
     private static Expression[] CreateArguments(ParameterInfo[]? parameters, FactoryContext factoryContext)
     {
         if (parameters is null || parameters.Length == 0)
@@ -1679,6 +1777,7 @@ private static async Task ExecuteResultWriteResponse(IResult? result, HttpContex
     private class FactoryContext
     {
         // Options
+        public IServiceProvider? ServiceProvider { get; init; }
         public IServiceProviderIsService? ServiceProviderIsService { get; init; }
         public List<string>? RouteParameters { get; init; }
         public bool ThrowOnBadRequest { get; init; }
@@ -1697,7 +1796,7 @@ private class FactoryContext
         public bool HasMultipleBodyParameters { get; set; }
         public bool HasInferredBody { get; set; }
 
-        public List<object> Metadata { get; } = new();
+        public List<object> Metadata { get; internal set; } = new();
 
         public NullabilityInfoContext NullabilityContext { get; } = new();
 

src/Http/Http.Extensions/src/RequestDelegateFactoryOptions.cs

@@ -12,7 +12,7 @@ namespace Microsoft.AspNetCore.Http;
 public sealed class RequestDelegateFactoryOptions
 {
     /// <summary>
-    /// The <see cref="IServiceProvider"/> instance used to detect if handler parameters are services.
+    /// The <see cref="IServiceProvider"/> instance used to access application services.
     /// </summary>
     public IServiceProvider? ServiceProvider { get; init; }
 
@@ -36,4 +36,15 @@ public sealed class RequestDelegateFactoryOptions
     /// The list of filters that must run in the pipeline for a given route handler.
     /// </summary>
     public IReadOnlyList<Func<RouteHandlerContext, RouteHandlerFilterDelegate, RouteHandlerFilterDelegate>>? RouteHandlerFilterFactories { get; init; }
+
+    /// <summary>
+    /// The initial endpoint metadata to add as part of the creation of the <see cref="RequestDelegateResult.RequestDelegate"/>.
+    /// </summary>
+    /// <remarks>
+    /// This metadata will be included in <see cref="RequestDelegateResult.EndpointMetadata" /> <b>before</b> any metadata inferred during creation of the
+    /// <see cref="RequestDelegateResult.RequestDelegate"/> and <b>before</b> any metadata provided by types in the delegate signature that implement
+    /// <see cref="IEndpointMetadataProvider" /> or <see cref="IEndpointParameterMetadataProvider" />, i.e. this metadata will be less specific than any
+    /// inferred by the call to <see cref="RequestDelegateFactory.Create(Delegate, RequestDelegateFactoryOptions?)"/>.
+    /// </remarks>
+    public IEnumerable<object>? InitialEndpointMetadata { get; init; }
 }