ASP.NET Core 中的端点约定生成器如何用法？-常见问题-PHP中文网

ASP.NET Core 中的端点约定生成器如何用法？

幻夢星雲

发布： 2025-09-24 22:55:01

原创

180人浏览过

EndpointConventionBuilder是ASP.NET Core中用于为路由端点添加元数据或配置策略的构建器对象，它在调用MapControllerRoute、MapRazorPages或Minimal API的MapGet等方法时由框架返回，支持链式调用以附加授权、CORS、缓存等约定。例如，通过RequireAuthorization()可为端点添加授权策略，Add()方法可直接操作元数据添加缓存头，还可扩展自定义约定如WithTraceTag添加日志标记，结合MapGroup可批量应用到多个端点，实现集中式配置管理。

asp.net core 中的端点约定生成器如何用法？

端点约定生成器（EndpointConventionBuilder）在 ASP.NET Core 中用于为路由端点附加元数据或配置策略，比如授权、CORS、缓存等。它不是直接创建的，而是在添加控制器、Razor 页面、Minimal API 等端点时由框架返回的一个构建器对象，你可以链式地为其添加约定。

1. 什么是 EndpointConventionBuilder？

当你使用 MapControllerRoute、MapRazorPages 或 MapGet/Post 等方法注册端点时，它们会返回一个 EndpointConventionBuilder 实例。你可以用这个实例来附加一些“约定”（conventions），这些约定会在路由构建时应用到对应的端点上。

2. 常见用法示例

为 Minimal API 添加授权：

app.MapGet("/api/values", () => "Hello")
   .RequireAuthorization(); // 返回 EndpointConventionBuilder

登录后复制

这里 RequireAuthorization() 是对 EndpointConventionBuilder 的扩展方法，它将授权策略添加到该端点。

为控制器路由添加缓存头：

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}")
.Add(b => b.Metadata.Add(new CacheProfile("DefaultCache")));

登录后复制

Add() 方法接收一个 Action<RouteEndpointBuilder>，允许你直接操作端点元数据。

自定义约定：添加日志标记

uBrand Logo生成器

uBrand Logo生成器是一款强大的AI智能LOGO设计工具。

查看详情

public static class MyEndpointConventionExtensions
{
    public static TBuilder WithTraceTag<TBuilder>(this TBuilder builder, string tag)
        where TBuilder : IEndpointConventionBuilder
    {
        builder.Add(endpointBuilder =>
        {
            if (endpointBuilder is RouteEndpointBuilder routeBuilder)
            {
                routeBuilder.Metadata.Add(new CustomTagMetadata(tag));
            }
        });
        return builder;
    }
}

登录后复制

然后在 Map 时使用：

app.MapGet("/info", () => "Info")
   .WithTraceTag("diagnostics");

登录后复制

3. 在 Controller 中使用 ApiController 特性组合

虽然不是直接调用 EndpointConventionBuilder，但 [ApiController] 实际上就是一种约定，它通过应用多个元数据影响行为。你也可以自定义特性并配合 ApplicationModel 来实现类似效果。

但在 Minimal API 或集中式路由中，EndpointConventionBuilder 提供了更灵活的运行时控制方式。

4. 与 MapGroup 结合使用

MapGroup 返回的是 RouteGroupBuilder，它也实现了 IEndpointConventionBuilder，所以可以批量设置：

var group = app.MapGroup("/api/v1")
               .RequireAuthorization()
               .WithOpenApi();

group.MapGet("/users", () => new[] { "Alice", "Bob" });
group.MapPost("/users", () => Results.Created());

登录后复制

这样所有属于该组的端点都会继承授权和 OpenAPI 描述。

基本上就这些。关键是理解：每次你调用 MapXXX 得到的对象支持链式配置，背后的机制就是 EndpointConventionBuilder 在收集你要附加的元数据或行为。不复杂但容易忽略其灵活性。

以上就是ASP.NET Core 中的端点约定生成器如何用法？的详细内容，更多请关注php中文网其它相关文章！