Menangani kesalahan di API ASP.NET Core

Nota

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi artikel .NET 10 ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan Inti .NET dan .NET. Untuk rilis saat ini, lihat versi artikel .NET 10 ini.

Artikel ini menjelaskan cara menangani kesalahan di API ASP.NET Core. Dokumentasi API Minimal telah dipilih. Untuk melihat dokumentasi API berbasis pengontrol, pilih tab Kontrol. Untuk panduan penanganan kesalahan Blazor, lihat kesalahan Handle di aplikasi ASP.NET Core Blazor.

Artikel ini menjelaskan cara menangani kesalahan di API ASP.NET Core. Dokumentasi untuk API berbasis Kendali dipilih. Untuk melihat dokumentasi untuk API Minimal, pilih tab API Minimal. Untuk panduan penanganan kesalahan Blazor, lihat kesalahan Handle di aplikasi ASP.NET Core Blazor.

Halaman Pengecualian Pengembang

Halaman Pengecualian Pengembang menampilkan informasi terperinci tentang pengecualian permintaan yang tidak tertangani. Ini menggunakan 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 dengan keduanya:

• Beroperasi di lingkungan.
• Aplikasi ini dibuat dengan templat saat ini, yaitu dengan menggunakan .

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

Peringatan

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

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

• Pelacakan tumpukan
• Parameter string kueri, jika ada
• Cookie, jika ada
• Headers
• Metadata untuk 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:

Halaman pengecualian pengembang dianimasikan untuk menampilkan setiap tab yang dipilih.

Menanggapi permintaan dengan 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 di API Minimal:

• Jalankan aplikasi sampel di lingkungan.
• Akses endpoint.

Bagian ini mengacu pada aplikasi sampel berikut untuk menunjukkan cara menangani pengecualian dalam API Minimal. Ini melemparkan pengecualian ketika titik akhir diminta:

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

Untuk melihat Halaman Pengecualian Pengembang di API berbasis pengontrol:

• Tambahkan tindakan pengontrol berikut ke API berbasis pengontrol. Tindakan menghasilkan pengecualian ketika titik akhir diminta.

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

• Jalankan aplikasi di lingkungan pengembangan.

• Pergi ke titik akhir yang ditentukan oleh aksi pengontrol.

Penangan pengecualian

Di lingkungan non-pengembangan, gunakan Middleware Penanganan Pengecualian untuk menghasilkan muatan kesalahan.

Untuk mengonfigurasi , panggil . Misalnya, kode berikut mengubah aplikasi agar merespons klien dengan payload yang sesuai dengan standar RFC 7807. Untuk informasi selengkapnya, lihat bagian Detail Masalah nanti di artikel ini.

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

1. Di sini, panggil 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 rute:

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

Tindakan sebelumnya mengirimkan payload yang mematuhi RFC 7807 ke klien.

Peringatan

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

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

[ApiExplorerSettings(IgnoreApi = true)]

Izinkan akses anonim ke metode jika pengguna yang tidak terautentikasi harus melihat kesalahan.

Respons kesalahan Klien dan Server

Pertimbangkan aplikasi API Minimal berikut.

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

Endpoint menghasilkan representasi ketika nilai lebih besar dari , jika tidak, hanya menghasilkan kode status tanpa isi respons. Untuk informasi selengkapnya tentang membuat respons, lihat Membuat respons di aplikasi API Minimal.

dapat dikonfigurasi untuk menghasilkan konten isi umum, ketika kosong, untuk semua respons klien HTTP () atau server (). Middleware dikonfigurasi dengan memanggil metode ekstensi UseStatusCodePages .

Misalnya, contoh berikut mengkonfigurasi aplikasi agar merespons dengan muatan data yang mematuhi RFC 7807 kepada klien untuk semua respons klien dan server, termasuk kesalahan perutean (misalnya, ). Untuk informasi selengkapnya, lihat bagian Detail Masalah .

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

Untuk API berbasis pengontrol, respons kesalahan dapat dikonfigurasi dengan salah satu cara berikut:

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

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

Pembuatan otomatis untuk kode status kesalahan diaktifkan secara default.

Detail masalah

Detail Masalah bukan satu-satunya format respons untuk menjelaskan kesalahan API HTTP, namun, biasanya digunakan untuk melaporkan kesalahan untuk API HTTP.

Layanan detail masalah mengimplementasikan antarmuka IProblemDetailsService, yang mendukung pembuatan detail masalah dalam ASP.NET Core. Metode ekstensi pada sistem ini mendaftarkan implementasi bawaan.

Dalam aplikasi ASP.NET Core, middleware berikut menghasilkan respons HTTP detail masalah saat dipanggil, kecuali ketika permintaan header HTTP tidak menyertakan salah satu jenis konten yang didukung oleh yang telah terdaftar (default: ):

• : Menghasilkan respons detail masalah saat handler kustom tidak ditentukan.
• : Menghasilkan respons detail masalah secara default.
• : Menghasilkan respons detail masalah dalam pengembangan ketika header HTTP permintaan tidak menyertakan .

Aplikasi API minimal dapat dikonfigurasi untuk menghasilkan respons detail masalah untuk semua respons kesalahan klien HTTP dan server yang belum memiliki konten isi dengan menggunakan metode ekstensi.

Kode berikut mengonfigurasi aplikasi untuk menghasilkan detail masalah:

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

Untuk informasi selengkapnya tentang menggunakan , lihat Detail Masalah

Fallback IProblemDetailsService

Dalam kode berikut, mengembalikan kesalahan jika implementasi tidak dapat menghasilkan :

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

Kode sebelumnya:

• Menulis pesan kesalahan dengan kode fallback jika tidak dapat menulis . Misalnya, titik akhir di mana header Permintaan terima menentukan jenis media yang tidak didukung.
• Menggunakan Middleware Penanganan Pengecualian.

Nota

mendukung jenis media berikut di header permintaan:

• application/json
• application/problem+json
• Jenis wildcard seperti dan

Jenis media non-JSON, seperti atau , tidak didukung dan akan memicu perilaku fallback.

Sampel berikut mirip dengan sebelumnya kecuali bahwa ia memanggil .

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

Layanan rincian masalah

ASP.NET Core mendukung pembuatan Detail Masalah untuk API HTTP menggunakan IProblemDetailsService.

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 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.

Menyesuaikan detail masalah dengan

Kode berikut menggunakan untuk mengatur :

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

Terapkan

MVC menggunakan untuk menghasilkan semua instans dan . Pabrik ini digunakan untuk:

• Respons kesalahan klien
• Respons kesalahan kegagalan validasi
• dan

Untuk menyesuaikan respons detail masalah, daftarkan implementasi kustom di :

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

Gunakan

Gunakan properti untuk mengonfigurasi konten respons. Misalnya, kode berikut dalam konteks tertentu memperbarui properti untuk respons 404.

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

Fitur penanganan kesalahan tambahan

Migrasi dari pengontrol ke API Minimal

Jika Anda bermigrasi dari API berbasis pengontrol ke API Minimal:

1. Mengganti filter tindakan dengan filter titik akhir atau middleware
2. Ganti validasi model dengan validasi manual atau pengikatan kustom
3. Ganti filter pengecualian dengan middleware penanganan pengecualian
4. Mengonfigurasi detail masalah menggunakan untuk respons kesalahan yang konsisten

Kapan menggunakan penanganan kesalahan berbasis pengontrol

Pertimbangkan API berbasis pengontrol jika Anda memerlukan:

• Skenario validasi model kompleks
• Penanganan pengecualian terpusat di beberapa pengontrol
• Kontrol terperinci atas pemformatan respons kesalahan
• Integrasi dengan fitur MVC seperti filter dan konvensi

Untuk informasi terperinci tentang penanganan kesalahan berbasis pengontrol, termasuk kesalahan validasi, kustomisasi detail masalah, dan filter pengecualian, lihat bagian tab Pengontrol .

Respons kesalahan kegagalan validasi

Untuk pengontrol API web, MVC merespons dengan jenis respons saat validasi model gagal. MVC menggunakan hasil untuk membangun respons kesalahan untuk kegagalan validasi. Contoh berikut mengganti factory default dengan implementasi yang juga mendukung memformat respons sebagai 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();

Gunakan pengecualian untuk mengubah respons

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

1. Buat jenis pengecualian terkenal bernama :

   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 action filter bernama :

   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 nilai bilangan bulat maksimum dikurangi 10. Ini memungkinkan filter lain berjalan di akhir pipeline.

3. Di , tambahkan filter tindakan ke kumpulan filter:

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

Perbedaan utama pada pengontrol

• Validasi model otomatis: Pengontrol secara otomatis memvalidasi status model dan mengembalikan respons untuk kegagalan validasi
• Filter pengecualian: Menggunakan filter tindakan dan filter pengecualian untuk penanganan kesalahan terpusat
• Detail masalah bawaan: Mengonfigurasi untuk respons kesalahan standar
• Respons kesalahan kustom: Mengambil alih pemformatan kesalahan validasi kustom

Sumber daya tambahan

• Cara Menggunakan Validasi ModelState di ASP.NET CORE Web API
• Tampilkan atau unduh kode sampel
• Hellang.Middleware.ProblemDetails