Menangani kesalahan di API web berbasis pengontrol inti ASP.NET

Artikel ini menjelaskan cara menangani kesalahan dan menyesuaikan penanganan kesalahan di API web ASP.NET Core berbasis pengontrol. Untuk informasi tentang penanganan kesalahan dalam API minimal, lihat Menangani kesalahan di ASP.NET Core dan Menangani kesalahan dalam API minimal.

Halaman Pengecualian Pengembang

Halaman Pengecualian Pengembang menampilkan informasi terperinci tentang pengecualian permintaan yang tidak tertangani. Ini menggunakan DeveloperExceptionPageMiddleware untuk menangkap pengecualian sinkron dan asinkron dari alur HTTP dan untuk menghasilkan respons kesalahan. Halaman pengecualian pengembang berjalan lebih awal di alur middleware, sehingga dapat menangkap pengecualian yang tidak tertangani yang dilemparkan dalam middleware yang mengikuti.

aplikasi ASP.NET Core mengaktifkan halaman pengecualian pengembang secara default saat keduanya:

• Berjalan di lingkungan Pengembangan.
• Aplikasi ini dibuat dengan templat saat ini, yaitu dengan menggunakan WebApplication.CreateBuilder.

Aplikasi yang dibuat menggunakan templat sebelumnya, yaitu, dengan menggunakan WebHost.CreateDefaultBuilder, dapat mengaktifkan halaman pengecualian pengembang dengan memanggil app.UseDeveloperExceptionPage.

Peringatan

Jangan aktifkan Halaman Pengecualian Pengembang kecuali aplikasi berjalan di lingkungan Pengembangan. Jangan bagikan informasi pengecualian terperinci secara publik saat aplikasi berjalan dalam produksi. Untuk informasi selengkapnya tentang mengonfigurasi lingkungan, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Halaman Pengecualian Pengembang dapat menyertakan informasi berikut tentang pengecualian dan permintaan:

• Pelacakan tumpukan
• Parameter string kueri, jika ada
• Cookie, jika ada
• Header
• Metadata titik akhir, jika ada

Halaman Pengecualian Pengembang tidak dijamin untuk memberikan informasi apa pun. Gunakan Pengelogan untuk informasi kesalahan lengkap.

Gambar berikut menunjukkan contoh halaman pengecualian pengembang dengan animasi untuk memperlihatkan tab dan informasi yang ditampilkan:

Menanggapi permintaan dengan Accept: text/plain header, Halaman Pengecualian Pengembang mengembalikan teks biasa alih-alih HTML. Contohnya:

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

Untuk melihat Halaman Pengecualian Pengembang:

• Tambahkan tindakan pengontrol berikut ke API berbasis pengontrol. Tindakan melemparkan pengecualian saat titik akhir diminta.

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

• Jalankan aplikasi di lingkungan pengembangan.

• Buka titik akhir yang ditentukan oleh tindakan pengontrol.

Handler pengecualian

Di lingkungan non-pengembangan, gunakan Middleware Penanganan Pengecualian untuk menghasilkan payload kesalahan:

1. Di Program.cs, panggil UseExceptionHandler untuk menambahkan Middleware Penanganan Pengecualian:

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

2. Konfigurasikan tindakan pengontrol untuk merespons /error rute:

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

Tindakan sebelumnya HandleError mengirimkan payload yang mematuhi RFC 7807 ke klien.

Peringatan

Jangan tandai metode tindakan penangan kesalahan dengan atribut metode HTTP, seperti HttpGet. Kata kerja eksplisit mencegah beberapa permintaan mencapai metode tindakan.

Untuk API web yang menggunakan Swagger / OpenAPI, tandai tindakan handler kesalahan dengan atribut [ApiExplorerSettings] dan atur propertinya IgnoreApi ke true. Konfigurasi atribut ini mengecualikan tindakan penanganan kesalahan dari spesifikasi OpenAPI aplikasi:

[ApiExplorerSettings(IgnoreApi = true)]

Izinkan akses anonim ke metode jika pengguna yang tidak diaturentikasi akan melihat kesalahan.

Middleware Penanganan Pengecualian juga dapat digunakan di lingkungan Pengembangan untuk menghasilkan format payload yang konsisten di semua lingkungan:

1. Dalam Program.cs, daftarkan instans Middleware Penanganan Pengecualian khusus lingkungan:

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

   Dalam kode sebelumnya, middleware terdaftar dengan:

   • Rute /error-development di lingkungan Pengembangan.
   • Rute /error di lingkungan non-Pengembangan.

2. Tambahkan tindakan pengontrol untuk rute Pengembangan dan non-Pengembangan:

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

Gunakan pengecualian untuk mengubah respons

Konten respons dapat dimodifikasi dari luar pengontrol menggunakan pengecualian kustom dan filter tindakan:

1. Buat jenis pengecualian terkenal bernama 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. Buat filter tindakan bernama 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;
           }
       }
   }
   

   Filter sebelumnya menentukan Order nilai bilangan bulat maksimum dikurangi 10. Ini Order memungkinkan filter lain berjalan di akhir alur.

3. Di Program.cs, tambahkan filter tindakan ke kumpulan filter:

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

Respons kesalahan kegagalan validasi

Untuk pengontrol API web, MVC merespons dengan ValidationProblemDetails jenis respons saat validasi model gagal. MVC menggunakan hasil InvalidModelStateResponseFactory untuk membangun respons kesalahan untuk kegagalan validasi. Contoh berikut mengganti pabrik default dengan implementasi yang juga mendukung respons pemformatan sebagai XML, di Program.cs:

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

Respons kesalahan klien

Hasil kesalahan didefinisikan sebagai hasilnya dengan kode status HTTP 400 atau lebih tinggi. Untuk pengontrol API web, MVC mengubah hasil kesalahan untuk menghasilkan ProblemDetails.

Pembuatan ProblemDetails otomatis untuk kode status kesalahan diaktifkan secara default, tetapi respons kesalahan dapat dikonfigurasi dengan salah satu cara berikut:

1. Menggunakan layanan detail masalah
2. Menerapkan ProblemDetailsFactory
3. Menggunakan ApiBehaviorOptions.ClientErrorMapping

Respons detail masalah default

File berikut Program.cs dihasilkan oleh templat aplikasi web untuk pengontrol API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Pertimbangkan pengontrol berikut, yang mengembalikan BadRequest ketika input tidak valid:

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

Respons detail masalah dihasilkan dengan kode sebelumnya ketika salah satu kondisi berikut berlaku:

• Titik /api/values2/divide akhir dipanggil dengan penyebut nol.
• Titik /api/values2/squareroot akhir dipanggil dengan radicand kurang dari nol.

Isi respons detail masalah default memiliki nilai , , titledan status berikuttype:

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

Layanan detail masalah

ASP.NET Core mendukung pembuatan Detail Masalah untuk API HTTP menggunakan IProblemDetailsService. Untuk informasi selengkapnya, lihat layanan Detail masalah.

Kode berikut mengonfigurasi aplikasi untuk menghasilkan respons detail masalah untuk semua respons kesalahan klien HTTP dan server yang belum memiliki konten isi:

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

Pertimbangkan pengontrol API dari bagian sebelumnya, yang mengembalikan BadRequest ketika input tidak valid:

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

Respons detail masalah dihasilkan dengan kode sebelumnya ketika salah satu kondisi berikut berlaku:

• Input yang tidak valid disediakan.
• URI tidak memiliki titik akhir yang cocok.
• Terjadi pengecualian yang tidak tertangani.

Pembuatan ProblemDetails otomatis untuk kode status kesalahan dinonaktifkan saat properti SuppressMapClientErrors diatur ke true:

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

Menggunakan kode sebelumnya, ketika pengontrol API mengembalikan BadRequest, status respons HTTP 400 dikembalikan tanpa isi respons. SuppressMapClientErrorsProblemDetails mencegah respons dibuat, bahkan saat memanggil WriteAsync titik akhir PENGONTROL API. WriteAsync dijelaskan kemudian dalam artikel ini.

Bagian berikutnya menunjukkan cara menyesuaikan isi respons detail masalah, menggunakan CustomizeProblemDetails, untuk mengembalikan respons yang lebih membantu. Untuk opsi penyesuaian lainnya, lihat Menyesuaikan detail masalah.

Menyesuaikan detail masalah dengan CustomizeProblemDetails

Kode berikut menggunakan ProblemDetailsOptions untuk mengatur 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();

Pengontrol API yang diperbarui:

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

}

Kode berikut berisi MathErrorFeature dan MathErrorType, yang digunakan dengan sampel sebelumnya:

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

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

Respons detail masalah dihasilkan dengan kode sebelumnya ketika salah satu kondisi berikut berlaku:

• Titik /divide akhir dipanggil dengan penyebut nol.
• Titik /squareroot akhir dipanggil dengan radicand kurang dari nol.
• URI tidak memiliki titik akhir yang cocok.

Isi respons detail masalah berisi hal berikut ketika salah satu squareroot titik akhir dipanggil dengan radicand kurang dari nol:

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

Menampilkan atau mengunduh kode sampel

Alat ProblemDetailsFactory

MVC menggunakan Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory untuk menghasilkan semua instans ProblemDetails dan ValidationProblemDetails. Pabrik ini digunakan untuk:

• Respons kesalahan klien
• Respons kesalahan kegagalan validasi
• ControllerBase.Problem dan ControllerBase.ValidationProblem

Untuk menyesuaikan respons detail masalah, daftarkan implementasi ProblemDetailsFactory kustom di Program.cs:

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

Menggunakan ApiBehaviorOptions.ClientErrorMapping

ClientErrorMapping Gunakan properti untuk mengonfigurasi konten ProblemDetails respons. Misalnya, kode berikut dalam Program.cs memperbarui Link properti untuk 404 respons:

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

Sumber Daya Tambahan:

• Cara Menggunakan Validasi ModelState di ASP.NET Core Web API
• Menampilkan atau mengunduh kode sampel
• Hellang.Middleware.ProblemDetails