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

注

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

Warnung

このバージョンの ASP.NET Coreはサポートされなくなりました。詳細については、.NETおよびコアサポートポリシー.NETを参照してください。現在のリリースについては、この記事の .NET 10 バージョンを参照してください。

最小限の API
Controllers

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

開発者例外ページ

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

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

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

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

Warnung

Development環境でアプリが実行されている場合を除き、開発者例外ページを有効にしないでください。アプリが運用環境で実行されている場合は、詳細な例外情報をパブリックに共有しないでください。環境の構成の詳細については、「ASP.NET Core ランタイム環境」を参照してください。

開発者例外ページには、例外と要求に関する次の情報を含めることができます。

スタックトレース
クエリ文字列パラメーター (存在する場合)
Cookies(ある場合)
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
Controllers

最小限の API で開発者例外ページを表示するには:

Development環境でサンプルアプリを実行します。
/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
Controllers

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

認証されていないユーザーにエラーが表示される場合は、メソッドへの匿名accessを許可します。

次の最小 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 のエラーを報告するために使用されます。

問題の詳細サービスは、ASP.NET Coreでの問題の詳細の作成をサポートする IProblemDetailsService インターフェイスを実装します。 AddProblemDetails(IServiceCollection) の IServiceCollection 拡張メソッドは、既定の IProblemDetailsService 実装を登録します。

ASP.NET Core アプリでは、AddProblemDetails が呼び出されたときに、次のミドルウェアによって問題の詳細 HTTP 応答が生成されます。ただし、Accept 要求 HTTP ヘッダーには、登録済みの IProblemDetailsWriter でサポートされているコンテンツタイプの 1 つが含まれていません (既定値: application/json)。

ExceptionHandlerMiddleware: カスタムハンドラーが定義されていない場合に、問題の詳細の応答を生成します。
StatusCodePagesMiddleware: 既定で問題の詳細の応答を生成します。
DeveloperExceptionPageMiddleware: 開発中に Accept 要求 HTTP ヘッダーに text/html が含まれていない場合に、問題の詳細応答を生成します。

最小限の API
Controllers

Minimal 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 要求ヘッダーが、 DefaultProblemDetailsWriter がサポートしていないメディアの種類を指定するエンドポイントです。
例外ハンドラーミドルウェアを使用します。

注

DefaultProblemDetailsWriterでは、Accept要求ヘッダーで次のメディアの種類がサポートされています。

application/json
application/problem+json
*/* や application/* のようなワイルドカード型

application/xmlやtext/htmlなどの JSON 以外のメディアの種類はサポートされておらず、フォールバック動作がトリガーされます。

次の例は、 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では、を使用した HTTP API の 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
Controllers

コントローラーから最小限の 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 をオーバーライドして、カスタムの検証エラーの書式を設定する

フィードバック

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

最終更新: 2026-10-10

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

開発者例外ページ

例外ハンドラー

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

問題の詳細

IProblemDetailsService フォールバック

その他のエラー処理機能

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

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

関連するコンテンツ

フィードバック

その他のリソース

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