ASP.NET Core Web API 异常处理

快速简单的异常处理

只需在 ASP.NET 路由之前将此中间件添加到您的中间件注册中。

app.UseExceptionHandler(c => c.Run(async context =>
{
    var exception = context.Features
        .Get<IExceptionHandlerPathFeature>()
        .Error;
    var response = new { error = exception.Message };
    await context.Response.WriteAsJsonAsync(response);
}));
app.UseMvc(); // or .UseRouting() or .UseEndpoints()

完毕！

为日志记录和其他目的启用依赖注入

步骤 1. 在您的启动中，注册您的异常处理路由：

// It should be one of your very first registrations
app.UseExceptionHandler("/error"); // Add this
app.UseEndpoints(endpoints => endpoints.MapControllers());

步骤 2. 创建将处理所有异常并产生错误响应的控制器：

[AllowAnonymous]
[ApiExplorerSettings(IgnoreApi = true)]
public class ErrorsController : ControllerBase
{
    [Route("error")]
    public MyErrorResponse Error()
    {
        var context = HttpContext.Features.Get<IExceptionHandlerFeature>();
        var exception = context.Error; // Your exception
        var code = 500; // Internal Server Error by default

        if      (exception is MyNotFoundException) code = 404; // Not Found
        else if (exception is MyUnauthException)   code = 401; // Unauthorized
        else if (exception is MyException)         code = 400; // Bad Request

        Response.StatusCode = code; // You can use HttpStatusCode enum instead

        return new MyErrorResponse(exception); // Your error model
    }
}

一些重要的注意事项和观察：

您可以将依赖项注入到 Controller 的构造函数中。

[ApiExplorerSettings(IgnoreApi = true)] 是必需的。否则，它可能会破坏你的 Swashbuckle 招摇

同样，app.UseExceptionHandler("/error");必须是 Startup Configure(...) 方法中最顶级的注册之一。将它放在方法的顶部可能是安全的。

app.UseExceptionHandler("/error") 和控制器 [Route("error")] 中的路径应该相同，以允许控制器处理从异常处理程序中间件重定向的异常。

这是 Microsoft 官方文档的 link。

响应模型的想法。

实现您自己的响应模型和异常。这个例子只是一个很好的起点。每个服务都需要以自己的方式处理异常。使用所描述的方法，您可以完全灵活地控制处理异常并从服务返回正确的响应。

错误响应模型的一个例子（只是给你一些想法）：

public class MyErrorResponse
{
    public string Type { get; set; }
    public string Message { get; set; }
    public string StackTrace { get; set; }

    public MyErrorResponse(Exception ex)
    {
        Type = ex.GetType().Name;
        Message = ex.Message;
        StackTrace = ex.ToString();
    }
}

对于更简单的服务，您可能希望实现如下所示的 http 状态代码异常：

public class HttpStatusException : Exception
{
    public HttpStatusCode Status { get; private set; }

    public HttpStatusException(HttpStatusCode status, string msg) : base(msg)
    {
        Status = status;
    }
}

这可以通过这种方式从任何地方抛出：

throw new HttpStatusCodeException(HttpStatusCode.NotFound, "User not found");

然后您的处理代码可以简化为：

if (exception is HttpStatusException httpException)
{
    code = (int) httpException.Status;
}

HttpContext.Features.Get<IExceptionHandlerFeature>() 什么？

ASP.NET Core 开发人员接受了中间件的概念，其中不同方面的功能（例如 Auth、MVC、Swagger 等）被分离并在请求处理管道中按顺序执行。每个中间件都可以访问请求上下文，并且可以在需要时写入响应。如果以与 MVC 异常相同的方式处理来自非 MVC 中间件的错误很重要，那么从 MVC 中取出异常处理是有意义的，我发现这在现实世界的应用程序中很常见。所以因为内置的异常处理中间件不是 MVC 的一部分，MVC 本身对此一无所知，反之亦然，异常处理中间件并不真正知道异常来自哪里，当然它知道它发生在某个地方请求执行的管道。但两者可能都需要相互“连接”。因此，当任何地方都没有捕获到异常时，异常处理中间件会捕获它并重新运行管道以获取在其中注册的路由。如果您愿意，这就是您可以使用一致的 content negotiation 或其他一些中间件将异常处理“传递”回 MVC 的方式。异常本身是从公共中间件上下文中提取的。看起来很有趣，但可以完成工作:)。

---

有一个内置的中间件：

ASP.NET Core 5 版本：

app.UseExceptionHandler(a => a.Run(async context =>
{
    var exceptionHandlerPathFeature = context.Features.Get<IExceptionHandlerPathFeature>();
    var exception = exceptionHandlerPathFeature.Error;
    
    await context.Response.WriteAsJsonAsync(new { error = exception.Message });
}));

旧版本（它们没有 WriteAsJsonAsync 扩展名）：

app.UseExceptionHandler(a => a.Run(async context =>
{
    var exceptionHandlerPathFeature = context.Features.Get<IExceptionHandlerPathFeature>();
    var exception = exceptionHandlerPathFeature.Error;
    
    var result = JsonConvert.SerializeObject(new { error = exception.Message });
    context.Response.ContentType = "application/json";
    await context.Response.WriteAsync(result);
}));

它应该做的几乎相同，只是要编写的代码少一点。

重要提示：请记住将其添加到 MapControllers \ UseMvc（或 .Net Core 3 中的 UseRouting）之前，因为顺序很重要。

---

您最好的选择是使用中间件来实现您正在寻找的日志记录。您希望将异常日志记录放在一个中间件中，然后在另一个中间件中处理向用户显示的错误页面。这允许逻辑分离并遵循 Microsoft 使用 2 个中间件组件制定的设计。这是 Microsoft 文档的一个很好的链接：Error Handling in ASP.Net Core

对于您的具体示例，您可能希望使用 StatusCodePage middleware 中的扩展程序之一或像 this 一样滚动您自己的扩展程序。

您可以在此处找到记录异常的示例：ExceptionHandlerMiddleware.cs

public void Configure(IApplicationBuilder app)
{
    // app.UseErrorPage(ErrorPageOptions.ShowAll);
    // app.UseStatusCodePages();
    // app.UseStatusCodePages(context => context.HttpContext.Response.SendAsync("Handler, status code: " + context.HttpContext.Response.StatusCode, "text/plain"));
    // app.UseStatusCodePages("text/plain", "Response, status code: {0}");
    // app.UseStatusCodePagesWithRedirects("~/errors/{0}");
    // app.UseStatusCodePagesWithRedirects("/base/errors/{0}");
    // app.UseStatusCodePages(builder => builder.UseWelcomePage());
    app.UseStatusCodePagesWithReExecute("/Errors/{0}");  // I use this version

    // Exception handling logging below
    app.UseExceptionHandler();
}

如果您不喜欢该特定实现，也可以使用 ELM Middleware，以下是一些示例：Elm Exception Middleware

public void Configure(IApplicationBuilder app)
{
    app.UseStatusCodePagesWithReExecute("/Errors/{0}");
    // Exception handling logging below
    app.UseElmCapture();
    app.UseElmPage();
}

如果这不能满足您的需求，您始终可以通过查看 ExceptionHandlerMiddleware 和 ElmMiddleware 的实现来滚动您自己的中间件组件，以掌握构建自己的概念。

在 StatusCodePages 中间件下方但在所有其他中间件组件上方添加异常处理中间件非常重要。这样，您的 Exception 中间件将捕获异常，记录它，然后允许请求继续到 StatusCodePage 中间件，该中间件将向用户显示友好的错误页面。

---

广为接受的答案对我帮助很大，但我想在我的中间件中传递 HttpStatusCode 以在运行时管理错误状态代码。

根据 this link，我有一些想法来做同样的事情。因此，我将 Andrei Answer 与此合并。所以我的最终代码如下：

1.基类

public class ErrorDetails
{
    public int StatusCode { get; set; }
    public string Message { get; set; }

    public override string ToString()
    {
        return JsonConvert.SerializeObject(this);
    }
}

2.自定义异常类类型

public class HttpStatusCodeException : Exception
{
    public HttpStatusCode StatusCode { get; set; }
    public string ContentType { get; set; } = @"text/plain";

    public HttpStatusCodeException(HttpStatusCode statusCode)
    {
        this.StatusCode = statusCode;
    }

    public HttpStatusCodeException(HttpStatusCode statusCode, string message) 
        : base(message)
    {
        this.StatusCode = statusCode;
    }

    public HttpStatusCodeException(HttpStatusCode statusCode, Exception inner) 
        : this(statusCode, inner.ToString()) { }

    public HttpStatusCodeException(HttpStatusCode statusCode, JObject errorObject) 
        : this(statusCode, errorObject.ToString())
    {
        this.ContentType = @"application/json";
    }

}

3.自定义异常中间件

public class CustomExceptionMiddleware
{
    private readonly RequestDelegate next;

    public CustomExceptionMiddleware(RequestDelegate next)
    {
        this.next = next;
    }

    public async Task Invoke(HttpContext context /* other dependencies */)
    {
        try
        {
            await next(context);
        }
        catch (HttpStatusCodeException ex)
        {
            await HandleExceptionAsync(context, ex);
        }
        catch (Exception exceptionObj)
        {
            await HandleExceptionAsync(context, exceptionObj);
        }
    }

    private Task HandleExceptionAsync(HttpContext context, HttpStatusCodeException exception)
    {
        string result = null;
        context.Response.ContentType = "application/json";
        if (exception is HttpStatusCodeException)
        {
            result = new ErrorDetails() 
            {
                Message = exception.Message,
                StatusCode = (int)exception.StatusCode 
            }.ToString();
            context.Response.StatusCode = (int)exception.StatusCode;
        }
        else
        {
            result = new ErrorDetails() 
            { 
                Message = "Runtime Error",
                StatusCode = (int)HttpStatusCode.BadRequest
            }.ToString();
            context.Response.StatusCode = (int)HttpStatusCode.BadRequest;
        }
        return context.Response.WriteAsync(result);
    }

    private Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        string result = new ErrorDetails() 
        { 
            Message = exception.Message,
            StatusCode = (int)HttpStatusCode.InternalServerError 
        }.ToString();
        context.Response.StatusCode = (int)HttpStatusCode.BadRequest;
        return context.Response.WriteAsync(result);
    }
}

4. 扩展方法

public static void ConfigureCustomExceptionMiddleware(this IApplicationBuilder app)
{
    app.UseMiddleware<CustomExceptionMiddleware>();
}

5.在startup.cs中配置Method

app.ConfigureCustomExceptionMiddleware();
app.UseMvc();

现在我在帐户控制器中的登录方法：

try
{
    IRepository<UserMaster> obj 
        = new Repository<UserMaster>(_objHeaderCapture, Constants.Tables.UserMaster);
    var result = obj.Get()
        .AsQueryable()
        .Where(sb => sb.EmailId.ToLower() == objData.UserName.ToLower() 
            && sb.Password == objData.Password.ToEncrypt() 
            && sb.Status == (int)StatusType.Active)
        .FirstOrDefault();
    if (result != null)//User Found
        return result;
    else // Not Found
        throw new HttpStatusCodeException(HttpStatusCode.NotFound,
            "Please check username or password");
}
catch (Exception ex)
{
    throw ex;
}

在上面你可以看到我是否还没有找到用户然后引发 HttpStatusCodeException 我在其中传递了 HttpStatusCode.NotFound 状态和中间件中的自定义消息

捕获（HttpStatusCodeException ex）

将调用blocked，它将控制权传递给

私有 Task HandleExceptionAsync(HttpContext context, HttpStatusCodeException 异常) 方法

但是如果我之前遇到运行时错误怎么办？为此，我使用了抛出异常的 try catch 块，并将在 catch (Exception exceptionObj) 块中捕获并将控制权传递给

任务 HandleExceptionAsync(HttpContext 上下文，异常异常)

方法。为了统一，我使用了一个 ErrorDetails 类。

---

要为每个异常类型配置异常处理行为，您可以使用 NuGet 包中的中间件：

Community.AspNetCore.ExceptionHandling.NewtonsoftJson 用于 ASP.NET Core 2.0

Community.AspNetCore.ExceptionHandling.Mvc 用于 ASP.NET Core 2.1+。

代码示例：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    services.AddExceptionHandlingPolicies(options =>
    {
        options.For<InitializationException>().Rethrow();

        options.For<SomeTransientException>().Retry(ro => ro.MaxRetryCount = 2).NextPolicy();

        options.For<SomeBadRequestException>()
        .Response(e => 400)
            .Headers((h, e) => h["X-MyCustomHeader"] = e.Message)
            .WithBody((req,sw, exception) =>
                {
                    byte[] array = Encoding.UTF8.GetBytes(exception.ToString());
                    return sw.WriteAsync(array, 0, array.Length);
                })
        .NextPolicy();

        // Ensure that all exception types are handled by adding handler for generic exception at the end.
        options.For<Exception>()
        .Log(lo =>
            {
                lo.EventIdFactory = (c, e) => new EventId(123, "UnhandlerException");
                lo.Category = (context, exception) => "MyCategory";
            })
        .Response(null, ResponseAlreadyStartedBehaviour.GoToNextHandler)
            .ClearCacheHeaders()
            .WithObjectResult((r, e) => new { msg = e.Message, path = r.Path })
        .Handled();
    });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseExceptionHandlingPolicies();
    app.UseMvc();
}

---

首先，感谢 Andrei，因为我的解决方案基于他的示例。

我包括我的，因为它是一个更完整的示例，可能会为读者节省一些时间。

Andrei 方法的局限性在于它不处理日志记录、捕获潜在有用的请求变量和内容协商（无论客户端请求什么，它都将始终返回 JSON - XML / 纯文本等）。

我的方法是使用 ObjectResult，它允许我们使用嵌入到 MVC 中的功能。

此代码还可以防止缓存响应。

错误响应已被修饰为可以由 XML 序列化程序序列化。

public class ExceptionHandlerMiddleware
{
    private readonly RequestDelegate next;
    private readonly IActionResultExecutor<ObjectResult> executor;
    private readonly ILogger logger;
    private static readonly ActionDescriptor EmptyActionDescriptor = new ActionDescriptor();

    public ExceptionHandlerMiddleware(RequestDelegate next, IActionResultExecutor<ObjectResult> executor, ILoggerFactory loggerFactory)
    {
        this.next = next;
        this.executor = executor;
        logger = loggerFactory.CreateLogger<ExceptionHandlerMiddleware>();
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, $"An unhandled exception has occurred while executing the request. Url: {context.Request.GetDisplayUrl()}. Request Data: " + GetRequestData(context));

            if (context.Response.HasStarted)
            {
                throw;
            }

            var routeData = context.GetRouteData() ?? new RouteData();

            ClearCacheHeaders(context.Response);

            var actionContext = new ActionContext(context, routeData, EmptyActionDescriptor);

            var result = new ObjectResult(new ErrorResponse("Error processing request. Server error."))
            {
                StatusCode = (int) HttpStatusCode.InternalServerError,
            };

            await executor.ExecuteAsync(actionContext, result);
        }
    }

    private static string GetRequestData(HttpContext context)
    {
        var sb = new StringBuilder();

        if (context.Request.HasFormContentType && context.Request.Form.Any())
        {
            sb.Append("Form variables:");
            foreach (var x in context.Request.Form)
            {
                sb.AppendFormat("Key={0}, Value={1}<br/>", x.Key, x.Value);
            }
        }

        sb.AppendLine("Method: " + context.Request.Method);

        return sb.ToString();
    }

    private static void ClearCacheHeaders(HttpResponse response)
    {
        response.Headers[HeaderNames.CacheControl] = "no-cache";
        response.Headers[HeaderNames.Pragma] = "no-cache";
        response.Headers[HeaderNames.Expires] = "-1";
        response.Headers.Remove(HeaderNames.ETag);
    }

    [DataContract(Name= "ErrorResponse")]
    public class ErrorResponse
    {
        [DataMember(Name = "Message")]
        public string Message { get; set; }

        public ErrorResponse(string message)
        {
            Message = message;
        }
    }
}

---

首先，将 ASP.NET Core 2 Startup 配置为针对来自 Web 服务器的任何错误和任何未处理的异常重新执行到错误页面。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment()) {
        // Debug config here...
    } else {
        app.UseStatusCodePagesWithReExecute("/Error");
        app.UseExceptionHandler("/Error");
    }
    // More config...
}

接下来，定义一个异常类型，允许您使用 HTTP 状态代码引发错误。

public class HttpException : Exception
{
    public HttpException(HttpStatusCode statusCode) { StatusCode = statusCode; }
    public HttpStatusCode StatusCode { get; private set; }
}

最后，在错误页面的控制器中，根据错误原因以及最终用户是否会直接看到响应来自定义响应。此代码假定所有 API URL 都以 /api/ 开头。

[AllowAnonymous]
public IActionResult Error()
{
    // Gets the status code from the exception or web server.
    var statusCode = HttpContext.Features.Get<IExceptionHandlerFeature>()?.Error is HttpException httpEx ?
        httpEx.StatusCode : (HttpStatusCode)Response.StatusCode;

    // For API errors, responds with just the status code (no page).
    if (HttpContext.Features.Get<IHttpRequestFeature>().RawTarget.StartsWith("/api/", StringComparison.Ordinal))
        return StatusCode((int)statusCode);

    // Creates a view model for a user-friendly error page.
    string text = null;
    switch (statusCode) {
        case HttpStatusCode.NotFound: text = "Page not found."; break;
        // Add more as desired.
    }
    return View("Error", new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier, ErrorText = text });
}

ASP.NET Core 将记录错误详细信息以供您调试，因此您可能只想向（可能不受信任的）请求者提供状态代码。如果您想显示更多信息，可以增强 HttpException 以提供它。对于 API 错误，您可以通过将 return StatusCode... 替换为 return Json... 将 JSON 编码的错误信息放入消息正文中。

---

通过添加您自己的“异常处理中间件”，当发生错误时，很难重用一些好的 built-in logic of Exception Handler，例如向客户端发送“符合 RFC 7807 的有效负载”。

我所做的是在 Startup.cs 类之外扩展 built-in Exception handler 以处理自定义异常或覆盖现有异常的行为。例如，一个 ArgumentException 并转换为 BadRequest 而不改变其他异常的默认行为：

在 Startup.cs 添加：

app.UseExceptionHandler("/error");

并使用以下内容扩展 ErrorController.cs：

using System;
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Hosting;

namespace Api.Controllers
{
    [ApiController]
    [ApiExplorerSettings(IgnoreApi = true)]
    [AllowAnonymous]
    public class ErrorController : ControllerBase
    {
        [Route("/error")]
        public IActionResult Error(
            [FromServices] IWebHostEnvironment webHostEnvironment)
        {
            var context = HttpContext.Features.Get<IExceptionHandlerFeature>();
            var exceptionType = context.Error.GetType();
            
            if (exceptionType == typeof(ArgumentException)
                || exceptionType == typeof(ArgumentNullException)
                || exceptionType == typeof(ArgumentOutOfRangeException))
            {
                if (webHostEnvironment.IsDevelopment())
                {
                    return ValidationProblem(
                        context.Error.StackTrace,
                        title: context.Error.Message);
                }

                return ValidationProblem(context.Error.Message);
            }

            if (exceptionType == typeof(NotFoundException))
            {
                return NotFound(context.Error.Message);
            }

            if (webHostEnvironment.IsDevelopment())
            {
                return Problem(
                    context.Error.StackTrace,
                    title: context.Error.Message
                    );
            }
            
            return Problem();
        }
    }
}

注意：

NotFoundException 是一个自定义异常，您需要做的就是 throw new NotFoundException(null);或 throw new ArgumentException("Invalid argument.");您不应向客户提供敏感的错误信息。服务错误是一种安全风险。

---

使用中间件或 IExceptionHandlerPathFeature 很好。 eshop 中还有另一种方法

创建一个异常过滤器并注册它

public class HttpGlobalExceptionFilter : IExceptionFilter
{
  public void OnException(ExceptionContext context)
  {...}
}

services.AddMvc(options =>
{
  options.Filters.Add(typeof(HttpGlobalExceptionFilter));
})

---

这里是 the official guideline from Microsoft，涵盖所有 .NET 版本的 WebAPI 和 MVC 案例。

对于 Web API，它建议重定向到专用控制器端点以返回 ProblemDetails。由于它可能会导致不打算直接调用的端点的 OpenAPI spec 潜在暴露，我建议使用更简单的解决方案：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseExceptionHandler(a => a.Run(async context =>
    {
        var error = context.Features.Get<IExceptionHandlerFeature>().Error;
        var problem = new ProblemDetails { Title = "Critical Error"};
        if (error != null)
        {
            if (env.IsDevelopment())
            {
                problem.Title = error.Message;
                problem.Detail = error.StackTrace;
            }
            else
                problem.Detail = error.Message;
        }
        await context.Response.WriteAsJsonAsync(problem);
    }));
    ...
}

在这种情况下，我们利用标准中间件返回自定义详细信息（带有开发模式的堆栈跟踪）并避免创建“内部”端点。

PS 请注意，the official guideline 在 .NET v3 之前和从那时起（截至目前的 v5）依赖于 IExceptionHandlerPathFeature - 在 IExceptionHandlerFeature 上。

PSS 如果您要从域层抛出异常以将它们转换为 4xx 代码，我建议使用 khellang's ProblemDetailsMiddleware 或返回可稍后转换为 IActionResult 或 IResult 的 DomainResult。后一个选项可帮助您在没有异常开销的情况下获得相同的结果。

---

处理任何特定方法的异常的简单方法是：

using Microsoft.AspNetCore.Http;
...

public ActionResult MyAPIMethod()
{
    try
    {
       var myObject = ... something;

       return Json(myObject);
    }
    catch (Exception ex)
    {
        Log.Error($"Error: {ex.Message}");
        return StatusCode(StatusCodes.Status500InternalServerError);
    }         
}

---

如果要为特定控制器设置自定义异常处理行为，可以通过覆盖控制器 OnActionExecuted 方法来实现。

请记住将 ExceptionHandled 属性设置为 true 以禁用默认异常处理行为。

这是我正在编写的 api 的示例，我想在其中捕获特定类型的异常并返回 json 格式的结果：

    private static readonly Type[] API_CATCH_EXCEPTIONS = new Type[]
    {
        typeof(InvalidOperationException),
        typeof(ValidationException)           
    };

    public override void OnActionExecuted(ActionExecutedContext context)
    {
        base.OnActionExecuted(context);

        if (context.Exception != null)
        {
            var exType = context.Exception.GetType();
            if (API_CATCH_EXCEPTIONS.Any(type => exType == type || exType.IsSubclassOf(type)))
            {
                context.Result = Problem(detail: context.Exception.Message);
                context.ExceptionHandled = true;
            }
        }  
    }

---