ASP.NET Core API'lerindeki hataları işleme

Uyarı

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için .NET ve .NET Core Destek Politikası'na bakın. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Minimum API'ler

Bu makalede, ASP.NET Çekirdek API'lerindeki hataların nasıl işleneceğini açıklanmaktadır. En Az API belgeleri seçildi. Denetleyici tabanlı API'lerin belgelerini görmek için Denetleyiciler sekmesini seçin. Hata işleme yönergeleri için Blazor bkz . ASP.NET Core Blazor uygulamalarında hataları işleme.

Denetleyici

Bu makalede, ASP.NET Çekirdek API'lerindeki hataların nasıl işleneceğini açıklanmaktadır. Denetleyici tabanlı API'ler için belgeler seçilidir. En Düşük API'lerin belgelerini görmek için En Az API sekmesini seçin. Hata işleme yönergeleri için Blazor bkz. ASP.NET Core Blazor uygulamalarında hataları işleme.

Geliştirici Özel Durum Sayfası

Geliştirici Özel Durum Sayfası, işlenmeyen istek özel durumları hakkında ayrıntılı bilgiler görüntüler. HTTP işlem hattından zaman uyumlu ve zaman uyumsuz özel durumları yakalamak ve hata yanıtları oluşturmak için kullanır DeveloperExceptionPageMiddleware . Geliştirici özel durum sayfası ara yazılım işlem hattında erken çalıştırılır, böylece izleyen ara yazılımda işlenmeyen özel durumları yakalayabilir.

ASP.NET Core uygulamaları, her ikisi de aşağıdaki durumlarda varsayılan olarak geliştirici özel durum sayfasını etkinleştirir:

• Geliştirme ortamında çalıştırılıyor.
• Uygulama, geçerli şablonlarla, yani kullanılarak WebApplication.CreateBuilderoluşturulmuştur.

Önceki şablonlar kullanılarak, yani kullanılarak WebHost.CreateDefaultBuilderoluşturulan uygulamalar, öğesini çağırarak app.UseDeveloperExceptionPagegeliştirici özel durum sayfasını etkinleştirebilir.

Uyarı

Uygulama Geliştirme ortamında çalışmadığı sürece Geliştirici Özel Durum Sayfası'nı etkinleştirmeyin. Uygulama üretimde çalışırken ayrıntılı özel durum bilgilerini herkese açık olarak paylaşmayın. Ortamları yapılandırma hakkında daha fazla bilgi için bkz. ASP.NET Core çalışma zamanı ortamları.

Geliştirici Özel Durum Sayfası, özel durum ve istek hakkında aşağıdaki bilgileri içerebilir:

• Yığın izleme
• Varsa sorgu dizesi parametreleri
• Varsa tanımlama bilgileri
• Headers
• Varsa uç nokta meta verileri

Geliştirici Özel Durum Sayfası'nın herhangi bir bilgi sağlaması garanti değildir. Tam hata bilgileri için Günlüğe Kaydetme özelliğini kullanın.

Aşağıdaki görüntüde, sekmeleri ve görüntülenen bilgileri gösteren animasyon içeren örnek bir geliştirici özel durum sayfası gösterilmektedir:

Üst bilgi içeren bir Accept: text/plain isteğe yanıt olarak, Geliştirici Özel Durum Sayfası HTML yerine düz metin döndürür. Örneğin:

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

Minimum API'ler

En Az API'de Geliştirici Özel Durum Sayfasını görmek için:

• Örnek uygulamayı Geliştirme ortamında çalıştırın.
• /exception Uç noktaya gidin.

Bu bölüm, En Az API'de özel durumları işlemenin yollarını göstermek için aşağıdaki örnek uygulamaya başvurur. Uç nokta /exception istendiğinde bir özel durum oluşturur:

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

Denetleyici

Denetleyici tabanlı api'de Geliştirici Özel Durum Sayfasını görmek için:

• Aşağıdaki denetleyici eylemini denetleyici tabanlı bir API'ye ekleyin. Eylem, uç nokta istendiğinde bir özel durum oluşturur.

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

• Uygulamayı geliştirme ortamında çalıştırın.

• Denetleyici eylemi tarafından tanımlanan uç noktaya gidin.

Özel durum işleyicisi

Geliştirme dışı ortamlarda hata yükü oluşturmak için Özel Durum İşleyici ara yazılımını kullanın.

Minimum API'ler

öğesini yapılandırmak için öğesini çağırınException Handler MiddlewareUseExceptionHandler. Örneğin, aşağıdaki kod uygulamayı istemciye RFC 7807 uyumlu bir yükle yanıt verecek şekilde değiştirir. Daha fazla bilgi için bu makalenin devamında yer alan Sorun Ayrıntıları bölümüne bakın.

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

Denetleyici

1. içinde Program.cs, Özel Durum İşleme Ara Yazılımını eklemek için öğesini çağırın UseExceptionHandler :

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

2. Bir denetleyici eylemini yola yanıt verecek şekilde /error yapılandırın:

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

Yukarıdaki HandleError eylem, istemciye RFC 7807 uyumlu bir yük gönderir.

Uyarı

Hata işleyicisi eylem yöntemini gibi HttpGetHTTP yöntemi öznitelikleriyle işaretlemeyin. Açık fiiller bazı isteklerin eylem yöntemine ulaşmasını engeller.

Swagger / OpenAPI kullanan web API'leri için hata işleyici eylemini [ApiExplorerSettings] özniteliğiyle işaretleyin ve özelliğini olarak IgnoreApiayarlayıntrue. Bu öznitelik yapılandırması, hata işleyici eylemini uygulamanın OpenAPI belirtiminin dışında tutar:

[ApiExplorerSettings(IgnoreApi = true)]

Kimliği doğrulanmamış kullanıcıların hatayı görmesi gerekiyorsa yönteme anonim erişime izin verin.

İstemci ve Sunucu hata yanıtları

Minimum API'ler

Aşağıdaki Minimal API uygulamasını göz önünde bulundurun.

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

Uç /users nokta 200 OKjson, ne zaman User değerinin değerinden id0 büyük olduğunu gösterir, aksi takdirde yanıt gövdesi olmayan bir 400 BAD REQUEST durum kodu oluşturur. Yanıt oluşturma hakkında daha fazla bilgi için bkz. Minimal API uygulamalarında yanıt oluşturma.

Status Code Pages middleware, tüm HTTP istemcisi () veya sunucu (400-499500 -) yanıtları için 599 ortak bir gövde içeriği üretecek şekilde yapılandırılabilir. Ara yazılım UseStatusCodePages uzantı yöntemi çağrılarak yapılandırılır.

Örneğin, aşağıdaki örnek uygulamayı yönlendirme hataları (örneğin, ) dahil olmak üzere tüm istemci ve sunucu yanıtları için istemciye 404 NOT FOUND uyumlu bir yükle yanıt verecek şekilde değiştirir. Daha fazla bilgi için Sorun Ayrıntıları bölümüne bakın.

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

Denetleyici

Denetleyici tabanlı API'ler için hata yanıtı aşağıdaki yollardan biriyle yapılandırılabilir:

1. Sorun ayrıntıları hizmetini kullanma
2. ProblemDetailsFactory Uygulama
3. ApiBehaviorOptions.ClientErrorMapping kullanma

Hata sonucu , 400 veya üzeri bir HTTP durum koduyla sonuç olarak tanımlanır. Web API denetleyicileri için, MVC bir hata sonucunu dönüştürerek bir ProblemDetailsoluşturur.

Hata durum kodları için otomatik oluşturma ProblemDetails varsayılan olarak etkindir.

Sorun ayrıntıları

Sorun Ayrıntıları , HTTP API hatasını açıklayan tek yanıt biçimi değildir, ancak genellikle HTTP API'lerine yönelik hataları bildirmek için kullanılır.

Sorun ayrıntıları hizmeti, ASP.NET Core'da sorun ayrıntıları oluşturmayı destekleyen arabirimini uygular IProblemDetailsService . AddProblemDetails(IServiceCollection) üzerindeki IServiceCollection uzantı yöntemi, varsayılan IProblemDetailsService uygulamayı kaydeder.

ASP.NET Core uygulamalarında aşağıdaki ara yazılım, AddProblemDetailsAccept http yanıtlarıyla ilgili sorun ayrıntıları oluşturur (varsayılan: ):IProblemDetailsWriter

• ExceptionHandlerMiddleware: Özel işleyici tanımlanmadığında bir sorun ayrıntıları yanıtı oluşturur.
• StatusCodePagesMiddleware: Varsayılan olarak bir sorun ayrıntıları yanıtı oluşturur.
• DeveloperExceptionPageMiddleware: İstek HTTP üst bilgisi içermediğinde Accepttext/htmlgeliştirme aşamasında bir sorun ayrıntıları yanıtı oluşturur.

Minimum API'ler

Uzantı yöntemi kullanılarak tüm HTTP istemci ve sunucu hata yanıtları için sorun ayrıntıları yanıtı oluşturmak üzere en az API uygulamaları yapılandırılabilir.

Aşağıdaki kod, uygulamayı sorun ayrıntıları oluşturacak şekilde yapılandırıyor:

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

kullanma AddProblemDetailshakkında daha fazla bilgi için bkz . Sorun Ayrıntıları

IProblemDetailsService geri dönüşü

Aşağıdaki kodda, httpContext.Response.WriteAsync("Fallback: An error occurred.") uygulama bir oluşturamıyorsa IProblemDetailsService bir ProblemDetailshata döndürür:

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

Önceki kod:

• bir yazamıyorsa problemDetailsService geri dönüş koduyla bir ProblemDetailshata iletisi yazar. Örneğin, Accept isteği üst bilgisinin desteklemediği bir medya türü DefaulProblemDetailsWriter belirttiği bir uç nokta.
• Özel Durum İşleyici ara yazılımını kullanır.

Aşağıdaki örnek, öğesini çağırması dışında öncekine Status Code Pages middlewarebenzer.

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

Denetleyici

Sorun ayrıntıları hizmeti

ASP.NET Core, kullanarak IProblemDetailsService oluşturmayı destekler.

Aşağıdaki kod, uygulamayı henüz gövde içeriği olmayan tüm HTTP istemcisi ve sunucu hata yanıtları için bir sorun ayrıntıları yanıtı oluşturacak şekilde yapılandırır:

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

Önceki bölümde yer alan ve giriş geçersiz olduğunda döndüren BadRequest API denetleyicisini göz önünde bulundurun:

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

Aşağıdaki koşullardan herhangi biri uygulandığında yukarıdaki kodla bir sorun ayrıntıları yanıtı oluşturulur:

• Geçersiz bir giriş sağlandı.
• URI'nin eşleşen uç noktası yok.
• İşlenmeyen bir özel durum oluşur.

Ile sorun ayrıntılarını özelleştirme CustomizeProblemDetails

Ayarlamak için ProblemDetailsOptionsaşağıdaki kod kullanılırCustomizeProblemDetails:

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

Araç ProblemDetailsFactory

MVC, ve Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory'nin ProblemDetails tüm örneklerini üretmek için kullanırValidationProblemDetails. Bu fabrika aşağıdakiler için kullanılır:

• İstemci hatası yanıtları
• Doğrulama hatası hata yanıtları
• ControllerBase.Problem ve ControllerBase.ValidationProblem

Sorun ayrıntıları yanıtını özelleştirmek için içindeki özel uygulamasını ProblemDetailsFactoryProgram.cskaydedin:

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

ApiBehaviorOptions.ClientErrorMapping komutunu kullanma

yanıtın ClientErrorMapping içeriğini ProblemDetails yapılandırmak için özelliğini kullanın. Örneğin, aşağıdaki kod Program.cs 404 yanıtları için özelliğini güncelleştirir Link :

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

Ek hata işleme özellikleri

Minimum API'ler

Denetleyicilerden En Düşük API'lere geçiş

Denetleyici tabanlı API'lerden En Düşük API'lere geçiş gerçekleştiriyorsanız:

1. Eylem filtrelerini uç nokta filtreleri veya ara yazılımla değiştirme
2. Model doğrulamayı el ile doğrulama veya özel bağlama ile değiştirme
3. Özel durum filtrelerini özel durum işleme ara yazılımıyla değiştirme
4. Tutarlı hata yanıtları için kullanarak AddProblemDetails()

Denetleyici tabanlı hata işleme ne zaman kullanılır?

Aşağıdakilere ihtiyacınız varsa denetleyici tabanlı API'leri göz önünde bulundurun:

• Karmaşık model doğrulama senaryoları
• Birden çok denetleyici arasında merkezi özel durum işleme
• Hata yanıtı biçimlendirmesi üzerinde ayrıntılı denetim
• Filtreler ve kurallar gibi MVC özellikleriyle tümleştirme

Doğrulama hataları, sorun ayrıntıları özelleştirmesi ve özel durum filtreleri de dahil olmak üzere denetleyici tabanlı hata işleme hakkında ayrıntılı bilgi için Denetleyiciler sekmesi bölümlerine bakın.

Denetleyici

Doğrulama hatası hatası yanıtı

Web API denetleyicileri için MVC, model doğrulaması başarısız olduğunda yanıt ValidationProblemDetails türüyle yanıt verir. MVC, doğrulama hatası için hata yanıtını oluşturmak için 'in InvalidModelStateResponseFactory sonuçlarını kullanır. Aşağıdaki örnek, içindeki varsayılan fabrikayı, yanıtları XML Program.csolarak biçimlendirmeyi de destekleyen bir uygulamayla değiştirir:

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

Yanıtı değiştirmek için özel durumları kullanma

Yanıtın içeriği özel bir özel durum ve eylem filtresi kullanılarak denetleyici dışından değiştirilebilir:

1. adlı HttpResponseExceptioniyi bilinen bir özel durum türü oluşturun:

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. adlı HttpResponseExceptionFilterbir eylem filtresi oluşturun:

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

   Yukarıdaki filtre, en büyük tamsayı değeri eksi 10 değerini belirtir Order . Bu Order , diğer filtrelerin işlem hattının sonunda çalışmasını sağlar.

3. içinde Program.cs, eylem filtresini filtreler koleksiyonuna ekleyin:

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

Denetleyiciler için önemli farklar

• Otomatik model doğrulama: Denetleyiciler model durumunu otomatik olarak doğrular ve doğrulama hataları için yanıtları döndürür 400 Bad Request
• Özel durum filtreleri: Merkezi hata işleme için eylem filtrelerini ve özel durum filtrelerini kullanma
• Yerleşik sorun ayrıntıları: Standartlaştırılmış hata yanıtları için yapılandırma ApiBehaviorOptions
• Özel hata yanıtları: Özel doğrulama hatası biçimlendirmesi için geçersiz kılma InvalidModelStateResponseFactory

Ek kaynaklar

• ASP.NET Core Web API'sinde ModelState Doğrulamasını Kullanma
• Örnek kodu görüntüleme veya indirme
• Hellang.Middleware.ProblemDetails