ASP.NET Core API のエラーを処理する

注

これは、この記事の最新バージョンではありません。現在のリリースについては、この記事の .NET 10 バージョンを参照してください。

Warnung

このバージョンの ASP.NET Core はサポート対象から除外されました。詳細については、 .NET および .NET Core サポートポリシーを参照してください。現在のリリースについては、この記事の .NET 9 バージョンを参照してください。

最小限の API
コントローラー

この記事では、ASP.NET Core API のエラーを処理する方法について説明します。最小限の API のドキュメントが選択されています。コントローラーベースの API のドキュメントを表示するには、[ コントローラー ] タブを選択します。エラー処理ガイダンス Blazor については、「 ASP.NET Core Blazor アプリでのエラーの処理」を参照してください。

開発者例外ページ

[開発者例外] ページには、未処理の要求例外に関する詳細情報が表示されます。 DeveloperExceptionPageMiddlewareを使用して、HTTP パイプラインから同期例外と非同期例外をキャプチャし、エラー応答を生成します。開発者例外ページはミドルウェアパイプラインの早い段階で実行されるため、次のミドルウェアでスローされたハンドルされない例外をキャッチできます。

ASP.NET Core アプリでは、次の両方の場合に開発者例外ページが既定で有効になります。

開発環境で実行されています。
アプリは、現在のテンプレート (つまり、 WebApplication.CreateBuilderを使用して) で作成されました。

以前のテンプレートを使用して作成されたアプリ(つまり、 WebHost.CreateDefaultBuilderを使用して)は、 app.UseDeveloperExceptionPageを呼び出すことによって開発者例外ページを有効にすることができます。

Warnung

開発環境でアプリが実行されている場合を除き、開発者例外ページを有効にしないでください。アプリが運用環境で実行されている場合は、詳細な例外情報をパブリックに共有しないでください。環境の構成の詳細については、「 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 準拠のペイロードをクライアントに送信します。

Warnung

エラーハンドラーアクションメソッドを、 HttpGetなどの HTTP メソッド属性でマークしないでください。明示的な動詞を使用すると、一部の要求がアクションメソッドに到達できなくなります。

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 OKがjsonより大きい場合はUserをid表現した0を生成します。それ以外の場合は、応答本文のない400 BAD REQUEST状態コードを生成します。応答の作成の詳細については、「最小限の API アプリで応答を作成する」を参照してください。

Status Code Pages middlewareは、すべての HTTP クライアント (400-) またはサーバー (499500 -) 応答に対して、共通の本文コンテンツ (599) を生成するように構成できます。ミドルウェアは、 UseStatusCodePages 拡張メソッドを呼び出すことによって構成されます。

たとえば、次の例では、ルーティングエラー ( など) を含むすべてのクライアントとサーバーの応答について、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: Accept 要求 HTTP ヘッダーに text/htmlが含まれていない場合に、開発中に問題の詳細応答を生成します。

最小限の 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);

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を記述できない場合は、フォールバックコードでエラーメッセージを書き込みます。たとえば、 Accept 要求ヘッダーが、 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 では、を使用した IProblemDetailsServiceの作成がサポートされています。

次のコードは、 本文の内容がまだないすべての 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();

入力が無効な場合に BadRequest を返す、前のセクションの 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 に一致するエンドポイントがありません。
ハンドルされない例外が発生します。

で問題の詳細をカスタマイズする `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();

道具 `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 プロパティを使用します。たとえば、 Program.cs の次のコードは、404 応答の Link プロパティを更新します。

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 の結果を使用して、検証エラーのエラー応答を構築します。次の例では、既定のファクトリを、 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();

例外を使用して応答を変更する

応答の内容は、カスタム例外とアクションフィルターを使用して、コントローラーの外部から変更できます。

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

上記のフィルターは、最大整数値から 10 を引いた Order を指定します。この Order では、パイプラインの最後に他のフィルターを実行できます。

Program.csで、アクションフィルターをフィルターコレクションに追加します。

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

コントローラーの主な違い

自動モデル検証: コントローラーはモデルの状態を自動的に検証し、検証エラーの 400 Bad Request 応答を返します
例外フィルター: 一元化されたエラー処理にアクションフィルターと例外フィルターを使用する
組み込みの問題の詳細: 標準化されたエラー応答用に ApiBehaviorOptions を構成する
カスタムエラー応答: カスタム検証エラーの書式設定の InvalidModelStateResponseFactory をオーバーライドする

その他のリソース

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-08-28

次の方法で共有

ASP.NET Core API のエラーを処理する

開発者例外ページ

例外ハンドラー

クライアントとサーバーのエラー応答

問題の詳細

IProblemDetailsService フォールバック

その他のエラー処理機能

コントローラーから最小限の API への移行

コントローラー ベースのエラー処理を使用する場合

その他のリソース

フィードバック

その他のリソース

コントローラーベースのエラー処理を使用する場合