Menangani kesalahan di API inti ASP.NET

Nota

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

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi lebih lanjut, lihat Kebijakan Dukungan .NET dan .NET Core . Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

API minimal

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

Controller

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

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

API minimal

Untuk melihat Halaman Pengecualian Pengembang di API Minimal:

• Jalankan aplikasi sampel di lingkungan Pengembangan.
• /exception Buka titik akhir.

Bagian ini mengacu pada aplikasi sampel berikut untuk menunjukkan cara menangani pengecualian dalam API Minimal. Ini melemparkan pengecualian ketika titik /exception 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();

Controller

Untuk melihat Halaman Pengecualian Pengembang di API berbasis pengontrol:

• 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 Handler Pengecualian untuk menghasilkan payload kesalahan.

API minimal

Untuk mengonfigurasi Exception Handler Middleware, panggil UseExceptionHandler. Misalnya, kode berikut mengubah aplikasi untuk merespons dengan payload yang mematuhi RFC 7807 ke klien. 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();

Controller

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.

Respons kesalahan Klien dan Server

API minimal

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

Titik /users akhir menghasilkan 200 OK dengan json representasi User kapan id lebih besar dari 0, jika tidak 400 BAD REQUEST , kode status tanpa isi respons. Untuk informasi selengkapnya tentang membuat respons, lihat Membuat respons di aplikasi API Minimal.

Status Code Pages middleware dapat dikonfigurasi untuk menghasilkan konten isi umum, ketika kosong, untuk semua respons klien HTTP (400-499) atau server (500 -599). Middleware dikonfigurasi dengan memanggil metode ekstensi UseStatusCodePages .

Misalnya, contoh berikut mengubah aplikasi untuk merespons dengan payload yang mematuhi RFC 7807 ke klien untuk semua respons klien dan server, termasuk kesalahan perutean (misalnya, 404 NOT FOUND). 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);

Controller

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

1. Menggunakan layanan detail masalah
2. Menerapkan ProblemDetailsFactory
3. Menggunakan 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 ProblemDetails.

Pembuatan ProblemDetails 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 IProblemDetailsService antarmuka, yang mendukung pembuatan detail masalah di ASP.NET Core. Metode AddProblemDetails(IServiceCollection) ekstensi pada IServiceCollection mendaftarkan implementasi default IProblemDetailsService .

Di aplikasi ASP.NET Core, middleware berikut menghasilkan respons HTTP detail masalah saat AddProblemDetails dipanggil, kecuali ketika Accept header HTTP permintaan tidak menyertakan salah satu jenis konten yang didukung oleh yang terdaftar IProblemDetailsWriter (default: application/json):

• ExceptionHandlerMiddleware: Menghasilkan respons detail masalah saat handler kustom tidak ditentukan.
• StatusCodePagesMiddleware: Menghasilkan respons detail masalah secara default.
• DeveloperExceptionPageMiddleware: Menghasilkan respons detail masalah dalam pengembangan ketika Accept header HTTP permintaan tidak menyertakan text/html.

API minimal

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 AddProblemDetails 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 AddProblemDetails, lihat Detail Masalah

Fallback IProblemDetailsService

Dalam kode berikut, httpContext.Response.WriteAsync("Fallback: An error occurred.") mengembalikan kesalahan jika IProblemDetailsService implementasi tidak dapat menghasilkan 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();

Kode sebelumnya:

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

Sampel berikut mirip dengan sebelumnya kecuali bahwa ia memanggil 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);

Controller

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

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

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

Gunakan 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";
    });

Fitur penanganan kesalahan tambahan

API minimal

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 AddProblemDetails() 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 .

Controller

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

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

Perbedaan utama untuk pengontrol

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

Sumber daya tambahan

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