处理 ASP.NET 核心 API 中的错误

2025-09-19

注释

此版本不是本文的最新版本。要查看当前版本，请参阅本文的.NET 9 版本。

警告

此版本的 ASP.NET Core 不再受支持。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。要查看当前版本，请参阅本文的.NET 9 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。

要查看当前版本，请参阅本文的.NET 9 版本。

最小 API
控制器

本文介绍如何处理 ASP.NET 核心 API 中的错误。已选择“最小 API”文档。若要查看基于控制器的 API 的文档，请选择 “控制器 ”选项卡。有关 Blazor 错误处理指南，请参阅在 ASP.NET Core Blazor 应用中处理错误。

开发人员异常页

开发人员异常页显示有关未经处理的请求异常的详细信息。它用于 DeveloperExceptionPageMiddleware 从 HTTP 管道捕获同步和异步异常，并生成错误响应。开发人员异常页在中间件管道中提前运行，以便它可以捕获在后面的中间件中引发的未经处理的异常。

ASP.NET 核心应用在以下两者中默认启用开发人员例外页：

在开发环境中运行。
应用是使用当前模板创建的，即使用 WebApplication.CreateBuilder。

使用早期模板创建的应用（即通过使用 WebHost.CreateDefaultBuilder）可以通过调用 app.UseDeveloperExceptionPage来启用开发人员例外页。

警告

除非 应用在开发环境中运行，否则不要启用开发人员异常页。当应用在生产环境中运行时，请勿公开共享详细的异常信息。有关配置环境的详细信息，请参阅 ASP.NET Core 运行时环境。

开发人员异常页可以包括有关异常和请求的以下信息：

堆栈跟踪
查询字符串参数（如果有）
Cookie（如果有）
Headers
终结点元数据（如果有）

不保证开发人员例外页提供任何信息。使用日志记录获取完整的错误信息。

下图显示了一个示例开发人员异常页，其中包含用于显示选项卡和显示的信息的动画：

开发人员异常页已动画显示所选的每个选项卡。

为了响应具有 Accept: text/plain 标头的请求，开发人员异常页返回纯文本而不是 HTML。例如：

Status: 500 Internal Server Error
Time: 9.39 msSize: 480 bytes
FormattedRawHeadersRequest
Body
text/plain; charset=utf-8, 480 bytes
System.InvalidOperationException: Sample Exception
   at WebApplicationMinimal.Program.<>c.<Main>b__0_0() in C:\Source\WebApplicationMinimal\Program.cs:line 12
   at lambda_method1(Closure, Object, HttpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

HEADERS
=======
Accept: text/plain
Host: localhost:7267
traceparent: 00-0eab195ea19d07b90a46cd7d6bf2f

最小 API
控制器

若要在最小 API 中查看开发人员异常页，请执行以下作：

在开发环境中运行示例应用。
转到 /exception 终结点。

本部分介绍以下示例应用，演示在最小 API 中处理异常的方法。当请求终结点 /exception 时，它会引发异常：

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

若要查看基于控制器的 API 中的开发人员异常页，请执行以下作：

将以下控制器作添加到基于控制器的 API。请求终结点时，该作将引发异常。
```
[HttpGet("Throw")]
public IActionResult Throw() =>
    throw new Exception("Sample exception.");
```
在开发环境中运行应用。
转到控制器作定义的终结点。

异常处理程序

在非开发环境中，使用异常处理程序中间件生成错误有效负载。

最小 API
控制器

若要配置 Exception Handler Middleware，请调用 UseExceptionHandler。例如，以下代码更改应用以响应符合 RFC 7807 的有效负载到客户端。有关详细信息，请参阅本文后面的 “问题详细信息 ”部分。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp 
    => exceptionHandlerApp.Run(async context 
        => await Results.Problem()
                     .ExecuteAsync(context)));

app.MapGet("/exception", () => 
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

在 Program.cs调用 UseExceptionHandler 中添加异常处理中间件：

var app = builder.Build();

app.UseHttpsRedirection();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/error");
}

app.UseAuthorization();

app.MapControllers();

app.Run();

配置控制器作以响应 /error 路由：

[Route("/error")]
public IActionResult HandleError() =>
    Problem();

上述 HandleError 作将符合 RFC 7807 的有效负载发送到客户端。

警告

不要使用 HTTP 方法属性标记错误处理程序作方法，例如 HttpGet。显式谓词可防止某些请求访问作方法。

对于使用 Swagger/OpenAPI 的 Web API，请使用 [ApiExplorerSettings] 属性标记错误处理程序作，并将其 IgnoreApi 属性设置为 true。此属性配置从应用的 OpenAPI 规范中排除错误处理程序作：

[ApiExplorerSettings(IgnoreApi = true)]

如果未经身份验证的用户应看到错误，则允许匿名访问该方法。

请考虑以下最小 API 应用。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

终结点/users生成的200 OKjson表示形式User为何时id大于0，否则400 BAD REQUEST为无响应正文的状态代码。有关创建响应的详细信息，请参阅 “在最小 API 应用中创建响应”。

Status Code Pages middleware可以配置为为所有 HTTP 客户端（）或服务器（400-）响应生成公共正文内容（499500 -599如果为空）。中间件是通过调用 UseStatusCodePages 扩展方法配置的。

例如，以下示例将应用更改为使用符合 RFC 7807 的有效负载向客户端响应所有客户端和服务器响应，包括路由错误（例如）。 404 NOT FOUND 有关详细信息，请参阅 “问题详细信息 ”部分。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.UseStatusCodePages(async statusCodeContext 
    => await Results.Problem(statusCode: statusCodeContext.HttpContext.Response.StatusCode)
                 .ExecuteAsync(statusCodeContext.HttpContext));

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

对于基于控制器的 API，可以通过以下方法之一配置错误响应：

使用问题详细信息服务
实现 ProblemDetailsFactory
使用 ApiBehaviorOptions.ClientErrorMapping

错误结果定义为 HTTP 状态代码为 400 或更高版本的结果。对于 Web API 控制器，MVC 转换错误结果以生成错误 ProblemDetails结果。

默认情况下启用自动创建 ProblemDetails 错误状态代码。

问题详细信息

问题详细信息不是描述 HTTP API 错误的唯一响应格式，但它们通常用于报告 HTTP API 的错误。

问题详细信息服务实现 IProblemDetailsService 接口，该接口支持在 ASP.NET Core 中创建问题详细信息。注册AddProblemDetails(IServiceCollection)默认IServiceCollection实现的扩展方法IProblemDetailsService。

在 ASP.NET Core 应用中，以下中间件在调用时AddProblemDetails会生成问题详细信息 HTTP 响应，但Accept请求 HTTP 标头不包含已注册IProblemDetailsWriter的内容类型之一（默认值）： application/json

ExceptionHandlerMiddleware：未定义自定义处理程序时生成问题详细信息响应。
StatusCodePagesMiddleware：默认生成问题详细信息响应。
DeveloperExceptionPageMiddleware：当请求 HTTP 标头不包含Accept时，text/html在开发中生成问题详细信息响应。

最小 API
控制器

可以将最小 API 应用配置为使用扩展方法为所有 HTTP 客户端和服务器错误响应生成问题详细信息响应，这些响应尚未AddProblemDetails包含正文内容。

以下代码将应用配置为生成问题详细信息：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

app.MapGet("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)));

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

有关使用 AddProblemDetails的详细信息，请参阅问题详细信息

IProblemDetailsService 回退

在以下代码中，如果httpContext.Response.WriteAsync("Fallback: An error occurred.")实现无法生成错误，IProblemDetailsService则返回错误ProblemDetails：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/exception", () =>
{
    throw new InvalidOperationException("Sample Exception");
});

app.MapGet("/", () => "Test by calling /exception");

app.Run();

前面的代码：

如果 problemDetailsService 无法编写回退代码，则编写 ProblemDetails错误消息。例如，接受请求标头指定不支持的 DefaulProblemDetailsWriter 媒体类型。
使用异常处理程序中间件。

下面的示例与前面的示例类似，只不过它调用了 Status Code Pages middleware.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseStatusCodePages(statusCodeHandlerApp =>
{
    statusCodeHandlerApp.Run(async httpContext =>
    {
        var pds = httpContext.RequestServices.GetService<IProblemDetailsService>();
        if (pds == null
            || !await pds.TryWriteAsync(new() { HttpContext = httpContext }))
        {
            // Fallback behavior
            await httpContext.Response.WriteAsync("Fallback: An error occurred.");
        }
    });
});

app.MapGet("/users/{id:int}", (int id) =>
{
    return id <= 0 ? Results.BadRequest() : Results.Ok(new User(id));
});

app.MapGet("/", () => "Test by calling /users/{id:int}");

app.Run();

public record User(int Id);

问题详细信息服务

ASP.NET Core 支持使用 <a0/> 为 HTTP API 创建问题详细信息。

以下代码将应用配置为为所有 尚未包含正文内容的 HTTP 客户端和服务器错误响应生成问题详细信息响应：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.MapControllers();
app.Run();

请考虑上一部分中的 API 控制器，该控制器在输入无效时返回 BadRequest ：

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

如果满足以下任一条件，则会使用上述代码生成问题详细信息响应：

提供了无效的输入。
URI 没有匹配的终结点。
发生未经处理的异常。

使用自定义问题详细信息

以下代码用于 ProblemDetailsOptions 设置 CustomizeProblemDetails：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails(options =>
        options.CustomizeProblemDetails = (context) =>
        {

            var mathErrorFeature = context.HttpContext.Features
                                                       .Get<MathErrorFeature>();
            if (mathErrorFeature is not null)
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError =>
                    ("Divison by zero is not defined.",
                                          "https://wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                                          "https://wikipedia.org/wiki/Square_root")
                };

                context.ProblemDetails.Type = details.Type;
                context.ProblemDetails.Title = "Bad Input";
                context.ProblemDetails.Detail = details.Detail;
            }
        }
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.UseStatusCodePages();

app.UseAuthorization();

app.MapControllers();

app.Run();

实现 `ProblemDetailsFactory`

MVC 用于Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory生成和 ProblemDetails. 的所有实例ValidationProblemDetails。此工厂用于：

客户端错误响应
验证失败错误响应
ControllerBase.Problem 和 ControllerBase.ValidationProblem

若要自定义问题详细信息响应，请注册以下项ProblemDetailsFactory的Program.cs自定义实现：

builder.Services.AddControllers();
builder.Services.AddTransient<ProblemDetailsFactory, SampleProblemDetailsFactory>();

使用 `ApiBehaviorOptions.ClientErrorMapping`

使用 ClientErrorMapping 属性配置响应的内容 ProblemDetails 。例如，更新 404 响应的属性的Program.csLink以下代码：

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

其他错误处理功能

最小 API
控制器

从控制器迁移到最小 API

如果要从基于控制器的 API 迁移到最小 API：

将作筛选器替换为终结点筛选器 或中间件
将模型验证替换为手动验证 或自定义绑定
将异常筛选器替换为 异常处理中间件
使用一致的错误响应AddProblemDetails()

何时使用基于控制器的错误处理

如果需要，请考虑基于控制器的 API：

复杂的模型验证方案
跨多个控制器集中处理异常
对错误响应格式的精细控制
与 MVC 功能（如筛选器和约定）集成

有关基于控制器的错误处理的详细信息，包括验证错误、问题详细信息自定义和异常筛选器，请参阅 “控制器 ”选项卡部分。

验证失败错误响应

对于 Web API 控制器，MVC 在模型验证失败时使用响应类型进行响应 ValidationProblemDetails 。 MVC 使用验证失败构造错误响应的结果 InvalidModelStateResponseFactory 。以下示例将默认工厂替换为一个实现，该实现还支持将响应的格式设置为 XML，在 Program.cs：

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

使用异常修改响应

可以使用自定义异常和作筛选器从控制器外部修改响应的内容：

创建名为 HttpResponseException：的已知异常类型：

public class HttpResponseException : Exception
{
    public HttpResponseException(int statusCode, object? value = null) =>
        (StatusCode, Value) = (statusCode, value);

    public int StatusCode { get; }

    public object? Value { get; }
}

创建名为 HttpResponseExceptionFilter：的作筛选器：

public class HttpResponseExceptionFilter : IActionFilter, IOrderedFilter
{
    public int Order => int.MaxValue - 10;

    public void OnActionExecuting(ActionExecutingContext context) { }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        if (context.Exception is HttpResponseException httpResponseException)
        {
            context.Result = new ObjectResult(httpResponseException.Value)
            {
                StatusCode = httpResponseException.StatusCode
            };

            context.ExceptionHandled = true;
        }
    }
}

前面的筛选器指定 Order 最大整数值减去 10。这样 Order ，其他筛选器就可以在管道末尾运行。

在 Program.cs中，将作筛选器添加到筛选器集合：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<HttpResponseExceptionFilter>();
});

控制器的主要差异

自动模型验证：控制器自动验证模型状态并返回 400 Bad Request 验证失败的响应
异常筛选器：使用作筛选器和异常筛选器进行集中错误处理
内置问题详细信息：配置 ApiBehaviorOptions 标准化错误响应
自定义错误响应：自定义验证错误格式的替代InvalidModelStateResponseFactory

其他资源

反馈

此页面是否有帮助？