處理 ASP.NET Core 控制器型 Web API 中的錯誤

本文描述如何在控制器型 ASP.NET Core Web API 處理錯誤以及自訂錯誤處理。 如需在基本 API 中錯誤處理的相關資訊，請參閱處理 ASP.NET Core 中的錯誤和在基本 API 中處理錯誤。

開發人員例外狀況頁面

「開發人員例外狀況頁面」會顯示未處理要求例外狀況的詳細資訊。 它會使用 DeveloperExceptionPageMiddleware 從 HTTP 管線中擷取同步和非同步例外狀況，並產生錯誤回應。 開發人員例外狀況頁面會在中介軟體管線的早期執行，以便它可以攔截在後續中介軟體中擲回的未處理的例外狀況。

當符合以下兩項條件時，ASP.NET Core 應用程式預設會啟用開發人員例外狀況頁面：

• 在開發環境中執行。
• 該應用程式是以目前的範本建立的，也就是使用 WebApplication.CreateBuilder。

使用舊版範本所建立的應用程式 (也就是使用 WebHost.CreateDefaultBuilder) 可以透過呼叫 app.UseDeveloperExceptionPage 來啟用開發人員例外狀況頁面。

警告

除非應用程式在開發環境中執行，否則請勿啟用 [開發人員例外狀況頁面]。 當應用程式在生產環境中執作時，請不要公開分享詳細的例外狀況資訊。 如需設定環境的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境。

「開發人員例外狀況頁面」可能包含下列有關例外狀況和要求的資訊：

• 堆疊追蹤
• 查詢字串參數 (如果有的話)
• Cookie，（如果有的話）
• 標頭
• 端點中繼資料 (如果有的話)

不保證「開發人員例外狀況頁面」提供任何資訊。 請使用記錄來取得完整的錯誤資訊。

下圖顯示了一個範例開發人員例外狀況頁面，並附有動畫來顯示索引標籤和顯示的資訊：

為了回應具有 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。 當要求端點時，此動作會擲回例外狀況。

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• 在開發環境中執行此應用程式。

• 移至控制器動作所定義的端點。

例外處理常式

在非開發環境中，使用例外狀況處理中介軟體來產生錯誤承載：

1. 在 Program.cs 中，呼叫 UseExceptionHandler 以新增「例外狀況處理中介軟體」：

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. 設定控制器動作，以回應 /error 路由：

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

上述 HandleError 動作會將符合 RFC 7807 規範的承載傳送至用戶端。

警告

請不要使用 HTTP 方法屬性 (如 HttpGet) 來標記錯誤處理常式動作方法。 明確的動詞可防止某些要求到達動作方法。

針對使用 Swagger/OpenAPI 的 Web API，請使用 [ApiExplorerSettings] 屬性來標記錯誤處理常式動作，並將其 IgnoreApi 屬性設定為 true。 此屬性設定會排除應用程式 OpenAPI 規格的錯誤處理常式動作：

[ApiExplorerSettings(IgnoreApi = true)]

如果未經驗證的使用者應該看到錯誤，則允許匿名存取方法。

「例外狀況處理中介軟體」也可以用於開發環境，以產生跨所有環境的一致承載格式：

1. 在 Program.cs 中，註冊環境特定的「例外狀況處理中介軟體」執行個體：

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   在上述程式碼中，會向下列項目註冊中介軟體：

   • 開發環境中 /error-development 的路由。
   • 非開發環境中 /error 的路由。

2. 新增開發和非開發路由的控制器動作：

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

使用例外狀況來修改回應

使用自訂例外狀況和動作篩選，可以從控制器外部修改回應的內容：

1. 建立名為 HttpResponseException 的已知例外狀況類型：

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

2. 建立名為 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;
           }
       }
   }
   

   上述篩選指定最大整數值減 10 的 Order。 此 Order 允許在管線結尾執行其他篩選。

3. 在 Program.cs 中，將動作篩選新增至 filters 集合：

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

驗證失敗錯誤回應

針對 Web API 控制器，MVC 會在模型驗證失敗時回應 ValidationProblemDetails 回應類型。 MVC 會使用 InvalidModelStateResponseFactory 的結果來建構驗證失敗的錯誤回應。 下列範例會在 Program.cs 中將預設處理站取代為也支援將回應格式化為 XML 的實作：

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

用戶端錯誤回應

「錯誤結果」定義為 HTTP 狀態碼為 400 或更高值的結果。 針對 Web API 控制器，MVC 會轉換錯誤結果，以產生 ProblemDetails。

預設會啟用自動建立 ProblemDetails 錯誤狀態碼，但可以使用下列其中一種方式來設定錯誤回應：

1. 使用問題詳細資料服務
2. Implement ProblemDetailsFactory
3. Use ApiBehaviorOptions.ClientErrorMapping

預設問題詳細資料回應

下列 Program.cs 檔案是由 API 控制器的 Web 應用程式範本所產生：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

請考慮下列控制器，其會在輸入無效時傳回 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));
    }
}

下列任一條件適用時，會使用上述程式碼產生問題詳細資料回應：

• 使用零分母來呼叫 /api/values2/divide 端點。
• 使用小於零的弧度來呼叫 /api/values2/squareroot 端點。

預設問題詳細資料回應本文具有下列 type、title 和 status 值：

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

問題詳細資料服務

ASP.NET Core 支援使用 IProblemDetailsService 來建立 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 沒有相符的端點。
• 發生未處理的例外狀況。

當 SuppressMapClientErrors 屬性設定為 true 時，系統會停用自動為錯誤狀態碼建立 ProblemDetails 的動作：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

如果使用上述程式碼，則在 API 控制器傳回 BadRequest 時，不會傳回 HTTP 400 回應狀態，而且沒有回應本文。 SuppressMapClientErrors 可防止建立 ProblemDetails 回應，即使針對 API 控制器端點呼叫 WriteAsync 時也是一樣。 本文稍後將說明 WriteAsync。

下節顯示如何使用 CustomizeProblemDetails 來自訂問題詳細資料回應本文，以傳回更實用的回應。 如需更多自訂選項，請參閱自訂問題詳細資料。

使用 CustomizeProblemDetails 來自訂問題詳細資料

下列程式碼會使用 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();

已更新的 API 控制器：

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

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

}

下列程式碼包含 MathErrorFeature 和 MathErrorType，其與上述範例搭配使用：

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

下列任一條件適用時，會使用上述程式碼產生問題詳細資料回應：

• 使用零分母來呼叫 /divide 端點。
• 使用小於零的弧度來呼叫 /squareroot 端點。
• URI 沒有相符的端點。

使用小於零的弧度來呼叫其中一個 squareroot 端點時，問題詳細資料回應本文會包含下列項目：

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

檢視或下載範例程式碼

實作 ProblemDetailsFactory

MVC 會使用 Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory 來產生所有 ProblemDetails 和 ValidationProblemDetails 執行個體。 此處理站用於：

• 用戶端錯誤回應
• 驗證失敗錯誤回應
• ControllerBase.Problem 和 ControllerBase.ValidationProblem

若要自訂問題詳細資料回應，請在 Program.cs 中註冊 ProblemDetailsFactory 的自訂實作：

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

使用 ApiBehaviorOptions.ClientErrorMapping

使用 ClientErrorMapping 屬性可設定 ProblemDetails 回應的內容。 例如，Program.cs 中的下列程式碼會更新 404 回應的 Link 屬性：

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

其他資源

• 如何在 ASP.NET Core Web API 中使用 ModelState 驗證
• 檢視或下載範例程式碼
• Hellang.Middleware.ProblemDetails