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ı

bu ASP.NET Core sürümü artık desteklenmiyor. Daha fazla bilgi için bkz. .NET ve .NET Çekirdek Destek İlkesi. Geçerli sürüm için bu makalenin .NET 10 sürümüne bakın.

Bu makalede, ASP.NET Core API'lerdeki hataların nasıl işleneceğini açıklanmaktadır. Minimal API belgeleri seçildi. Denetleyici tabanlı API'lerin belgelerini görmek için Controllers sekmesini seçin. Blazor hata işleme kılavuzu için bkz. ASP.NET Core Blazor uygulamalarında Handle hataları.

Bu makalede, ASP.NET Core API'lerdeki hataların nasıl işleneceğini açıklanmaktadır. Denetleyici tabanlı API'ler için belgeler seçilidir. Minimal API belgelerini görmek için Minimal API sekmesini seçin. Blazor hata işleme kılavuzu için bkz. ASP.NET Core Blazor uygulamalarında Handle hataları.

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 bunu kullanır. Geliştirici istisna sayfası, ara yazılım işlem hattının başlarında çalıştırılır, böylece takip eden ara yazılımda işlenmemiş istisnaları yakalayabilir.

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

• Çalışma ortamında çalıştırılıyor.
• Uygulama, geçerli şablonlarla, yani kullanılarak oluşturulmuştur.

Önceki şablonlar kullanılarak, yani kullanılarak oluşturulan uygulamalar, 'ı çağırarak geliştirici özel durum sayfasını etkinleştirebilir.

Uyarı

Uygulama ortamda ç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ük Kaydı 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:

Geliştirici özel durum sayfası, her seçilen sekmeyi göstermek için animasyonludur.

Üst bilgi içeren bir 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

Minimal API'de Geliştirici İstisna Sayfasını görmek için:

• Ortamda örnek uygulamayı çalıştırın.
• Uç noktasına 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 istendiğinde bir hata durumu 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 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.

öğesini yapılandırmak için öğesini çağırın. Ö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();

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

   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 yapılandırın:

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

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

Uyarı

Hata işleyicisi eylem yöntemini GET, POST gibi HTTP 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 ayarlayın. 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ı

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

API uç noktası, değer belirtilenden büyük olduğunda bir gösterim ile sonuç üretir, aksi takdirde yanıt gövdesi olmayan bir durum kodu döndürür. Yanıt oluşturma hakkında daha fazla bilgi için bkz. Minimal API uygulamalarında yanıt oluşturma.

Bu, tüm HTTP istemcisi veya sunucu yanıtları için boş olduğunda 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ı gibi tüm istemci ve sunucu yanıtları için istemciye RFC 7807 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 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'i Uygula
3. ApiBehaviorOptions.ClientErrorMapping'i kullanın

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 hata mesajı veya sonuç üretir.

Hata durum kodları için otomatik oluşturma 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'de sorun ayrıntıları oluşturmayı destekleyen IProblemDetailsService arabirimini uygular. üzerindeki uzantı yöntemi, varsayılan uygulamayı kaydeder.

ASP.NET Core uygulamalarında, çağrıldığında ve isteği HTTP üst bilgisi kayıtlı tarafından desteklenen içerik türlerinden birine sahip değilse (varsayılan: ), aşağıdaki ara yazılım sorun detayları HTTP yanıtları üretir.

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

Minimal API'ler, gövde içeriği olmayan tüm HTTP istemci ve sunucu hata yanıtları için sorun ayrıntıları yanıtı oluşturmak üzere uzantı yöntemi kullanılarak 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 hakkında daha fazla bilgi için bkz . Sorun Ayrıntıları

IProblemDetailsService geri dönüşü

Aşağıdaki kodda, uygulama bir oluşturamıyorsa bir hata 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:

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

Uyarı

, istek üst bilgisinde aşağıdaki medya türlerini destekler:

• application/json
• application/problem+json
• Joker karakter türleri, örneğin ... ve ...

veya gibi JSON olmayan medya türleri desteklenmez ve geri dönüş davranışını tetikler.

Aşağıdaki örnek, öğesini çağırması dışında öncekine benzer.

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

Sorun ayrıntıları hizmeti

ASP.NET Core, HTTP API'leri için Sorun Ayrıntıları oluşturmayı IProblemDetailsService kullanarak 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 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.

Sorun ayrıntılarını özelleştirme.

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

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

Uygulamak

MVC, ve 'nin tüm örneklerini üretmek için kullanır. Bu fabrika aşağıdakiler için kullanılır:

• İstemci hatası yanıtları
• Doğrulama başarısızlığı hata yanıtları
• ve

Sorun ayrıntıları yanıtını özelleştirmek için, belirtilen alandaki özel bir uygulamayı kaydedin:

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

komutunu kullanma

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

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

Ek hata işleme özellikleri

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ı manuel doğrulama veya özel bağlama ile değiştirin
3. Özel durum filtrelerini özel durum işleme ara yazılımıyla değiştirme
4. Hata ayrıntılarını kullanarak yapılandırarak tutarlı hata yanıtları oluşturun.

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.

Doğrulama hatası yanıtı

Web API denetleyicileri için MVC, model doğrulaması başarısız olduğunda yanıt türüyle yanıt verir. MVC, doğrulama hatası için hata yanıtını oluşturmak için 'in sonuçlarını kullanır. Aşağıdaki örnek, içindeki varsayılan fabrikayı, yanıtları XML olarak 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ı iyi 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ı bir 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;
           }
       }
   }
   

   Önceki filtre, maksimum tamsayı değerinin eksi 10'unu belirtir. Bu , diğer filtrelerin işlem hattının sonunda çalışmasını sağlar.

3. içinde , 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
• Ö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
• Özel hata yanıtları: Özel doğrulama hatası biçimlendirmesi için geçersiz kılma

Ek kaynaklar

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