ASP.NET 7 中的 EndpointFilter

Intro

.NET 6 开始微软引入了 Minimal API，但是相比成熟的控制器模型，还是有很多的不足，.NET 7 针对于 Minimal API 也做了一些改进来让 Minimal API 功能更加丰富，其中 Filter 就是其中的一个更新

从 .NET 7 Preview 3 开始，开始引入 filter 的支持，最初 filter 定义的接口是 IRouteHandlerFilter，添加 filter 的时候是在对应 endpoint 上调用 AddFilter 去注册 filter，从 .NET 7 preview 7 开始 IRouteHandlerFilter 变成了 IEndpointFilter，注册方式也变成了 AddEndpointFilter

EndpointFilter

下面来看几个示例：

var app = WebApplication.Create(args);
app.Map("/", () => "Hello MinimalAPI")
    .AddEndpointFilter<OutputDotNetVersionFilter>();
app.Run();

OutputDotNetVersionFilter 是一个实现 IEndpointFilter 的强类型的过滤器，实现如下：

public sealed class OutputDotNetVersionFilter : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        context.HttpContext.Response.Headers["X-NET-Version"] = System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription;
        return await next(context);
    }
}

我们来测试一下我们的 filter 是否有生效，运行起来项目之后测试一下我们的 API

可以看到我们的 response header 里已经有了我们 filter 里增加的 X-NET-Version 响应头了

我们也可以使用一个委托来注册 filter，示例如下：

app.Map("/hhh", () => "Minimal API")
    .AddEndpointFilter(async (context, next) =>
    {
        if (context.HttpContext.Request.QueryString.HasValue)
        {
            return await next(context);
        }
        return Results.Ok(new { Name = "test", Date = DateTime.Today });
    });

可以看到我们的结果已经变成了 filter 中的结果

当传了任意一个 query 参数的时候还是原来的 response 内容

你也可以注册一个 IEndpointFilter 实例，例如：

app.Map("/NotFound", () => "Not Found")
    .AddEndpointFilter(new EnvironmentFilter("Production")

.NET 7 也为 Minimal API 引入了一个 MapGroup 来更好对 endpoint 进行分组和组织，你也可以结合 MapGroup 来为多个 endpoint 同时注册 filter 例如：

var testGroup1 = app.MapGroup("/test1");
testGroup1.Map("/hello", () => "Hello");
testGroup1.Map("/world", () => "World");
testGroup1.AddEndpointFilter<ApiResultFilter>();

测试一下可以看到这个 group 中的两个 endpoint 都会被这个 filter 处理，类比控制器，可以理解为这两个 API 同属于一个 controller，而我们在控制器上加了一个 filter

EndpointFilter 和 asp.net core 的中间件很像，你可以注册许多个，也可以在某个 filter 中进行中断，不往下走，在某种情景下拦截后续的处理，可以自己实践一下~

使用 MapGroup 方式，pattern 设置为空字符串 MapGroup("") 也可以注册全局 filter 但是需要把所有的 endpoint 都在这个 group 下注册，有些不太方便，提了一个 issue 已经在 .NET 8 的 plan 里了，.NET 8 应该会针对全局的 filter 有更好的支持，具体可以参考 issue: https://github.com/dotnet/aspnetcore/issues/43237

References

https://github.com/WeihanLi/WeihanLi.Web.Extensions/blob/dev/samples/WeihanLi.Web.Extensions.Samples/Program.cs
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/min-api-filters?view=aspnetcore-7.0
https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-7-preview-6/
https://devblogs.microsoft.com/dotnet/asp-net-core-updates-in-dotnet-7-preview-3/#support-for-route-handler-filters-in-minimal-apis
https://github.com/dotnet/aspnetcore/issues/43237