ApiController 属性

该[ApiController]属性可以应用于控制器类以启用以下自以为是的、特定于 API 的行为：

• 属性路由要求
• 自动 HTTP 400 响应
• 绑定源参数推断
• 多部分/表单数据请求推断
• 错误状态代码的问题详细信息

特定控制器上的属性

该[ApiController]属性可以应用于特定的控制器，如项目模板中的以下示例所示：

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

多个控制器上的属性

在多个控制器上使用该属性的一种方法是创建一个使用该[ApiController]属性注释的自定义基本控制器类。以下示例显示了一个自定义基类和一个从它派生的控制器：

[ApiController]
public class MyControllerBase : ControllerBase
{
}

[Produces(MediaTypeNames.Application.Json)]
[Route("[controller]")]
public class PetsController : MyControllerBase

程序集上的属性

该[ApiController]属性可以应用于程序集。当[ApiController]属性应用于程序集时，程序集中的所有控制器都[ApiController]应用了该属性。无法选择退出单个控制器。将程序集级属性应用于Program.cs文件：

using Microsoft.AspNetCore.Mvc;
[assembly: ApiController]

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

属性路由要求

属性使[ApiController]属性路由成为一项要求。例如：

C＃复制

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

无法通过UseMvc或UseMvcWithDefaultRoute定义的常规路由访问操作。UseEndpoints

自动 HTTP 400 响应

该[ApiController]属性使模型验证错误自动触发 HTTP 400 响应。因此，动作方法中不需要以下代码：

if (!ModelState.IsValid)
{
    return BadRequest(ModelState);
}

ASP.NET Core MVC 使用ModelStateInvalidFilter操作筛选器来执行上述检查。

默认 BadRequest 响应

以下请求正文是序列化类型的示例：

JSON复制

{
  "": [
    "A non-empty request body is required."
  ]
}

HTTP 400 响应的默认响应类型是ValidationProblemDetails。以下请求正文是序列化类型的示例：

JSON复制

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "|7fb5e16a-4c8f23bbfc974667.",
  "errors": {
    "": [
      "A non-empty request body is required."
    ]
  }
}

ValidationProblemDetails类型：

• 提供一种机器可读的格式，用于指定 Web API 响应中的错误。
• 符合RFC 7807 规范。

要使自动响应和自定义响应保持一致，请调用ValidationProblem方法而不是BadRequest。ValidationProblem返回一个ValidationProblemDetails对象以及自动响应。

记录自动 400 响应

要记录自动 400 响应，请设置InvalidModelStateResponseFactory委托属性以执行自定义处理。默认情况下，InvalidModelStateResponseFactory使用ProblemDetailsFactory创建ValidationProblemDetails的实例。

以下示例显示如何检索ILogger<TCategoryName>的实例以记录有关自动 400 响应的信息：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
      // To preserve the default behavior, capture the original delegate to call later.
        var builtInFactory = options.InvalidModelStateResponseFactory;

        options.InvalidModelStateResponseFactory = context =>
        {
            var logger = context.HttpContext.RequestServices
                                .GetRequiredService<ILogger<Program>>();

            // Perform logging here.
            // ...

            // Invoke the default behavior, which produces a ValidationProblemDetails
            // response.
            // To produce a custom response, return a different implementation of 
            // IActionResult instead.
            return builtInFactory(context);
        };
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

禁用自动 400 响应

要禁用自动 400 行为，请将SuppressModelStateInvalidFilter属性设置为true。添加以下突出显示的代码：

using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

绑定源参数推断

绑定源属性定义了找到动作参数值的位置。存在以下绑定源属性：

警告

[FromRoute]当值可能包含%2f（即）时不要使用/。%2f不会逃到/. 如果[FromQuery]值可能包含%2f.

如果没有[ApiController]属性或绑定源属性（如[FromQuery]），ASP.NET Core 运行时会尝试使用复杂对象模型绑定器。复杂对象模型绑定器以定义的顺序从值提供者中提取数据。

该[ApiController]属性对动作参数的默认数据源应用推理规则。这些规则使您不必通过将属性应用于操作参数来手动识别绑定源。绑定源推理规则的行为如下：

• [FromBody]为未在 DI 容器中注册的复杂类型参数推断。推理规则的一个例外[FromBody]是任何具有特殊含义的复杂内置类型，例如IFormCollection和CancellationToken。绑定源推理代码忽略那些特殊类型。
• [FromForm]为IFormFile和IFormFileCollection类型的操作参数推断。它不会针对任何简单或用户定义的类型进行推断。
• [FromRoute]为与路由模板中的参数匹配的任何操作参数名称推断。当多个路由匹配一个动作参数时，任何路由值都会被考虑[FromRoute]。
• [FromQuery]为任何其他动作参数推断。