ASP.NET Core コントローラーベースの Web API でエラーを処理する

この記事では、コントローラーベースの ASP.NET Core Web API でエラーを処理し、エラー処理をカスタマイズする方法について説明します。 Minimal API でのエラー処理の詳細については、「ASP.NET Core のエラーを処理する」と Minimal 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 準拠のペイロードをクライアントに送信します。

警告

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

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 に、フィルター コレクションに対するアクション フィルターを追加します。

   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. ProblemDetailsFactory の実装
3. 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 エンドポイントは、0 分母で呼び出されます。
• /api/values2/squareroot エンドポイントは、0 未満の被開平数で呼び出されます。

既定の問題の詳細応答本文には、次の 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();

入力が無効な場合に 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 に一致するエンドポイントがありません。
• ハンドルされない例外が発生しました。

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 は、API コントローラー エンドポイント用に WriteAsync を呼び出す場合でも、ProblemDetails 応答が作成されないようにします。 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 エンドポイントは、0 分母で呼び出されます。
• /squareroot エンドポイントは 0 未満の被開平数で呼び出されます。
• URI に一致するエンドポイントがありません。

いずれかの squareroot エンドポイントが 0 未満の被開平数で呼び出された場合、問題の詳細応答本文には次のものが含まれます:

{
  "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 を使用します

ProblemDetails の応答の内容を構成するには、ClientErrorMapping プロパティを使用します。 たとえば、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