ASP.NET Core 中的自定义约定如何应用？-C#.Net教程-PHP中文网

ASP.NET Core 中的自定义约定如何应用？

月夜之吻

发布： 2025-10-21 12:59:01

原创

721人浏览过

自定义约定是通过实现IControllerModelConvention或IActionModelConvention接口，统一配置Web API路由与行为的机制。它可用于自动添加路由前缀、设置响应格式、集成Swagger等。例如，RoutePrefixConvention为所有控制器添加“/api/v1”前缀，需在AddControllers时注册；AddCacheConvention标记GET方法以启用缓存，通过action.Properties传递状态；SwaggerTagByAreaConvention则按Area分组API。关键在于操作ControllerModel或ActionModel的属性，并注意避免覆盖显式路由设置，适合批量配置以减少重复代码。

asp.net core 中的自定义约定如何应用？

在 ASP.NET Core 中，自定义约定（Custom Conventions）主要用于 Web API 的路由和控制器行为的配置，特别是在使用 API 探索工具如 Swagger（Swashbuckle）或进行基于约定的配置时。它们允许你在不修改每个控制器或动作方法的前提下，统一应用某些规则。

什么是自定义约定？

自定义约定是通过实现特定接口来扩展 ASP.NET Core MVC 行为的机制。常见的应用场景包括：

自动为所有控制器添加路由前缀
统一设置响应格式（如强制返回 JSON）
为 API 添加版本号或公共查询参数
与 Swagger 集成时自动添加注释或标签

主要涉及两类约定：

• 控制器级别约定（IControllerModelConvention）
• 操作级别约定（IActionModelConvention）

如何创建并注册自定义控制器约定

以添加全局路由前缀为例：

// 自定义控制器约定：为所有控制器添加前缀

public class RoutePrefixConvention : IControllerModelConvention
{
    private readonly string _prefix;

    public RoutePrefixConvention(string prefix)
    {
        _prefix = prefix;
    }

    public void Apply(ControllerModel controller)
    {
        // 只对没有显式标记 [Route] 的控制器生效
        if (controller.Selectors.Any(s => s.AttributeRouteModel != null))
            return;

        foreach (var selector in controller.Selectors)
        {
            selector.AttributeRouteModel = new AttributeRouteModel
            {
                Template = $"/{_prefix}/{controller.ControllerName}"
            };
        }
    }
}

登录后复制

在 Program.cs 中注册：

builder.Services.AddControllers(options =>
{
    options.Conventions.Add(new RoutePrefixConvention("api/v1"));
});

登录后复制

这样所有控制器默认都会映射到 /api/v1/控制器名 路径下。

操作级别的自定义约定示例

比如你想为所有 GET 方法自动添加缓存头说明：

稿定AI绘图

稿定推出的AI绘画工具

查看详情

public class AddCacheConvention : IActionModelConvention
{
    public void Apply(ActionModel action)
    {
        if (action.HttpMethods != null && action.HttpMethods.Contains("GET"))
        {
            // 可用于记录或标记，例如配合过滤器使用
            action.Properties["IsCached"] = true;
        }
    }
}

登录后复制

注册方式相同：

options.Conventions.Add(new AddCacheConvention());

登录后复制

后续可在中间件、过滤器或文档生成中读取 action.Properties 进行处理。

与 Swagger 结合使用

常用于自动添加标签或描述：

public class SwaggerTagByAreaConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        var area = controller.RouteValues["area"];
        if (!string.IsNullOrEmpty(area))
        {
            foreach (var action in controller.Actions)
            {
                action.ApiExplorer.GroupName = area;
            }
        }
    }
}

登录后复制

这能让 Swagger UI 按 Area 分组展示 API。

基本上就这些。自定义约定适合做“批量配置”，避免重复代码。只要搞清楚 ControllerModel 和 ActionModel 的结构，就能灵活控制路由、元数据和文档行为。关键是注册位置要正确，在 AddControllers 里添加即可生效。不复杂但容易忽略细节，比如判断是否已有 AttributeRouteModel。

以上就是ASP.NET Core 中的自定义约定如何应用？的详细内容，更多请关注php中文网其它相关文章！