處理 ASP.NET Core API 中的錯誤

備註

這不是本文的最新版本。關於目前版本，請參閱本文的 .NET 10 版本。

警告

此版本的 ASP.NET Core 已不再支援。欲了解更多資訊，請參閱.NET及.NET核心支援政策。關於目前版本，請參閱本文的 .NET 10 版本。

最少的 API
控制器

本文說明如何處理 ASP.NET Core API 中的錯誤。已選取 [最小 API] 的檔案。若要查看控制器基礎 API 的文件，請選擇 Controllers 標籤。關於 Blazor 錯誤處理指引，請參見 ASP.NET Core Blazor 應用程式中的錯誤處理。

開發人員例外頁面

開發人員例外狀況頁面會顯示未處理要求例外狀況的詳細資訊。它用來從 HTTP 管線擷取同步和非同步例外狀況，並產生錯誤回應。開發人員例外狀況頁面會在中介程式管線的早期執行，因此它可以攔截在後續中介程式中拋出的未處理例外狀況。

ASP.NET Core 應用程式預設啟用開發者例外頁面，當兩者同時：

在環境中運行。
應用程式是使用目前的範本建立的，也就是使用。

使用舊版範本建立的應用程式，亦即使用，可以透過呼叫來啟用開發人員例外狀況頁面。

警告

除非應用程式在環境中執行，否則不要啟用開發者例外頁面。當應用程式在生產環境中執行時，請勿公開共用詳細的例外狀況資訊。欲了解更多關於環境配置的資訊，請參見 ASP.NET Core runtime environments。

開發人員例外狀況頁面可以包含例外狀況和要求的下列相關資訊：

堆疊追蹤
查詢字串參數（如果有的話）
Cookies（如有）
Headers
端點中繼資料（如果有的話）

開發人員例外狀況頁面不保證提供任何資訊。請利用日誌記錄以取得完整的錯誤資訊。

下圖顯示範例開發人員例外狀況頁面，其中包含動畫，以顯示索引標籤和顯示的資訊：

開發人員例外狀況頁面會以動畫形式顯示選取的每個索引標籤。

為了回應具有標頭的要求，開發人員例外狀況頁面會傳回純文字，而不是 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 中查看開發人員例外狀況頁面：

在環境中執行範例應用程式。
前往端點。

本節參考下列範例應用程式，以示範在最小 API 中處理例外狀況的方法。當請求該端點時，它會拋出例外：

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
控制器

若要設定，請呼叫。例如，下列程式碼將應用程式變更為向用戶端回傳符合 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();

在中，呼叫新增異常處理中間件：

var app = builder.Build();

app.UseHttpsRedirection();

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

app.UseAuthorization();

app.MapControllers();

app.Run();

設定控制器動作以回應路由：

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

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

警告

請勿在錯誤處理器動作方法上使用 HTTP 方法屬性。明確的動詞會防止某些請求到達行為方法。

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

[ApiExplorerSettings(IgnoreApi = true)]

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

用戶端和伺服器錯誤回應

最少的 API
控制器

請考慮下列最小 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);

端點會在某參數大於特定值時返回表示該結果的表示法，否則會返回不含回應內容的狀態碼。如需建立回應的詳細資訊，請參閱在最小 API 應用程式中建立回應。

可以配置為在空時為所有 HTTP 用戶端（）或伺服器（）回應產生通用內文內容。中介軟體是藉由呼叫 UseStatusCodePages 擴充方法來設定。

舉例來說，下列範例會變更應用程式，以符合 RFC 7807 規範的承載回應用戶端，以回應所有用戶端和伺服器回應，包括路由錯誤（例如）。如需詳細資訊，請參閱問題詳細資料一節。

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);

問題詳細資料

問題詳細資料不是描述 HTTP API 錯誤的唯一回應格式，不過，它們通常用來報告 HTTP API 的錯誤。

問題詳細服務實作了 IProblemDetailsService 介面，支援在 ASP.NET Core 中建立問題細節。上的擴充方法會註冊預設實作。

在 ASP.NET Core應用程式中，當呼叫 AddProblemDetails 時，以下中介軟體會產生問題細節 HTTP 回應，除非 Accept 請求標頭不包含註冊的 IProblemDetailsWriter（預設：application/json 所支援的內容類型）：

：在未定義自訂處理常式時產生問題詳細資料回應。
：依預設會產生問題詳細資料回應。
當開發環境中發現 HTTP 請求標頭未包含指定元素時，系統將產生問題詳細資訊回應。

最少的 API
控制器

可以使用擴充方法將最小 API 應用程式設定為對於尚未包含內容的所有 HTTP 用戶端和伺服器錯誤回應產生問題詳細資料回應。

下列程式碼會設定應用程式以產生問題詳細資料：

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);

如需有關使用的詳細資訊，請參閱問題詳細資料

IProblemDetailsService 後備

在以下程式碼中，當實作無法產生所需內容時，將回傳錯誤。

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();

上述程式碼：

如果無法寫入，則會寫入帶有後援代碼的錯誤訊息。例如，一個端點，其 Accept 請求標頭指定了媒體類型，而該媒體類型不被支持。
使用例外處理中介軟體。

備註

在請求標頭中支援以下媒體類型：

application/json
application/problem+json
百用字元類型，如和

非 JSON 媒體類型，如或，不被支援，並會觸發備援行為。

下列範例與上述範例類似，只是它會呼叫。

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 支援使用 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 控制器，當輸入無效時會傳回：

[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 沒有相符的端點。
發生未處理的異常狀況。

自訂問題詳細資料

以下程式碼用於設定：

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();

實施

MVC 會用來產生和的所有實例。該工廠用於：

用戶端錯誤回應
驗證失敗錯誤回應
和

若要自訂問題詳細資料的回應，請註冊一個自訂實作。

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

使用

使用屬性來設定回應的內容。例如，下列程式碼會更新 404 回應的屬性：

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

其他錯誤處理功能

最少的 API
控制器

從控制器移轉至最小API

如果您要從控制器型 API 移轉至最小 API：

將動作篩選器取代為端點篩選器或中介軟體
將模型驗證取代為手動驗證或自訂繫結
將異常篩選器取代為異常處理中介軟體
設定問題詳細資料，以取得一致的錯誤回應

何時使用控制器型錯誤處理

如果您需要，請考慮以控制器為基礎的 API：

複雜的模型驗證案例
跨多個控制器的集中式異常處理
對錯誤回應格式的精細控制
與篩選器和約定等 MVC 功能整合

如需控制器型錯誤處理的詳細資訊，包括驗證錯誤、問題詳細資料自訂和異常狀況篩選器，請參閱控制器索引標籤區段。

驗證失敗錯誤回應

針對 Web API 控制器，MVC 會在模型驗證失敗時以回應類型回應。 MVC 會使用某些結果來建構驗證失敗的錯誤回應。下列範例會將預設 Factory 取代為也支援將回應格式化為 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();

使用例外狀況來修改回應

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

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

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

    public int StatusCode { get; }

    public object? Value { get; }
}

建立名為的動作篩選器：

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 的過濾條件。這可讓其他篩選器在管線結尾執行。

在中，將動作篩選器新增至篩選器集合：

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

控制器的主要差異

自動模型驗證：控制器自動驗證模型狀態並傳回驗證失敗的回應
異常篩選器：使用動作篩選器和異常篩選器進行集中式錯誤處理
內建問題詳細資料：設定標準化錯誤回應
自訂錯誤回應：覆寫自訂驗證錯誤格式

其他資源

如何在 ASP.NET Core Web API 中使用 ModelState 驗證
查看或下載範例代碼
Hellang.Middleware.ProblemDetails

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-05

共用方式為

處理 ASP.NET Core API 中的錯誤

開發人員例外頁面

例外狀況處理常式

用戶端和伺服器錯誤回應

問題詳細資料

IProblemDetailsService 後備

其他錯誤處理功能

從控制器移轉至最小API

何時使用控制器型錯誤處理

其他資源

意見反應

其他資源