Support global endpoint filters and metadata on WebApplication

[captainsafia]

Background and Motivation

In the past, there have been requests to support adding endpoint filters at the global level (see #43237). More recently, the need for global filters has emerged as part of the work to support a source generator-based validation implementation in minimal APIs (see #46349).

Endpoint filters are implemented on top of ASP.NET Core's conventions API and the IEndpointConventionBuilder. To support global filters, we'll need to expose an API for accessing an underlying IEndpointConventionBuilder on the top-level WebApplication.

Proposed API

// Assembly: Microsoft.AspNetCore
namespace Microsoft.AspNetCore.Builder;

public sealed class WebApplication : IHost, IApplicationBuilder, IEndpointRouteBuilder, IAsyncDisposable
{
+  public IEndpointConventionBuilder Conventions { get; }
}

Usage Examples

var app = WebApplication.Create();

// Register parameter validations for minimal APIs globally
app.Conventions.WithValidation();

// Disable anti-forgery checks on form-based endpoints during development
if (app.Environment.IsDevelopment())
{
  app.Conventions.DisableAntiforgery();
}

// Require authorization on all endpoints in the application
app.Conventions.RequireAuthorization();

app.MapGet("/", () => "Hello world!");

app.Run();

Alternative Designs

Instead of exposing the IEndpointConventionBuilder as a property on the WebApplication class, we can consider implementing the IEndpointConventionBuilder interface directly on the class.

// Assembly: Microsoft.AspNetCore
namespace Microsoft.AspNetCore.Builder;

public sealed class WebApplication : IHost, IApplicationBuilder, IEndpointRouteBuilder, IAsyncDisposable, IEndpointConventionBuilder
{
+  public void Add(Action<EndpointBuilder> convention) { }
+  public void Finally(Action<EndpointBuilder> finallyConvention) { }
}

However, there's hesitation around having WebApplication implement the IEndpointConventionBuilder which is an interface with multiple extension methods (ref) that might pollute the API surface for the WebApplication. Isolating these extension methods to a property keeps the Intellisense on WebApplication clean. On the other hand, there are discoverability questions around the Conventions property.

Alternatively, we can consider exposing a deconstructor on the WebApplication class that allows the user to pull out the underlying IEndpointConventionBuillder.

// Assembly: Microsoft.AspNetCore
namespace Microsoft.AspNetCore.Builder;

public sealed class WebApplication : IHost, IApplicationBuilder, IEndpointRouteBuilder, IAsyncDisposable
{
+  public void Deconstruct(out IEndpointConventionBuilder conventions) { }
}

Risks

• The name Conventions comes from an implementation details of the framework and is not as familiar to users as related terms like "filter" and "metadata", which map to conventions under the hood. This might impact the discoverability of this feature.
• Supporting global filters on WebApplication means that users will need to understand the distinction between global middleware and global filters. We'll need to make sure that the distinction is clear to users who might not be familiar with the different pipelines.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.