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

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. Bu, HTTP işlem hattından zaman uyumlu ve zaman uyumsuz özel durumları yakalamak ve hata yanıtları oluşturmak için DeveloperExceptionPageMiddleware 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:

Daha önceki şablonlar, yani WebHost.CreateDefaultBuilder kullanılarak oluşturulan uygulamalar, app.UseDeveloperExceptionPage çağrılarak geliştirici özel durum sayfasını etkinleştirebilir.

Uyarı

Uygulama ortamda çalışmadığı sürece Geliştirici Özel Durum Sayfası'nı Developmentetkinleş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
  • Cookies, varsa
  • 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 ö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:

Seçilen her sekmeyi göstermek için animasyonlu geliştirici özel durum sayfası.

Ü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

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

  • Ortamda örnek uygulamayı Developmentçalıştırın.
  • /exception 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. /exception uç noktasına istekte bulunulduğunda bir özel durum fırlatır:

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

Özel durum işleyicisi

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

exception handler middleware öğesini yapılandırmak için UseExceptionHandler öğ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();

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

/users uç noktası, 200 OKjson değerinden büyük olduğunda, User öğesinin id gösterimiyle 0 oluşturur; aksi takdirde, yanıt gövdesi olmadan 400 BAD REQUEST durum kodu üretir. 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 istemci (400-) veya sunucu (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ı da (örneğin, ) dahil olmak üzere tüm istemci ve sunucu yanıtlarında istemciye 404 NOT FOUND uyumlu bir yanıt gövdesi döndürecek ş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);

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. AddProblemDetails(IServiceCollection) üzerindeki IServiceCollection uzantı yöntemi, varsayılan IProblemDetailsService 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.

Minimal API uygulamaları, uzantı yöntemi kullanılarak, tüm HTTP istemci ve sunucu hata yanıtları için problem ayrıntıları yanıtı oluşturacak şekilde 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);

AddProblemDetails kullanımı hakkında daha fazla bilgi için bkz. Sorun Ayrıntıları

Hatalı istek işlemeyi RouteHandlerOptions.ThrowOnBadRequest ile özelleştirin

Minimal API parametre bağlaması hatalı istek hatalarıyla karşılaştığında (hatalı biçimlendirilmiş JSON veya tür dönüştürme hataları gibi), hata işleme ThrowOnBadRequest tarafından denetlenir:

  • Development ortamında, ThrowOnBadRequest varsayılan olarak true olur. Hatalı istek bağlama hataları bir UseExceptionHandler oluşturur; bu, özel durum işleme ara yazılımından (IExceptionHandler) geçer ve Sorun Ayrıntıları yanıtları oluşturmak için kayıtlı BadHttpRequestException işleyicilerini (ASP.NET Core 8 ve sonraki sürümlerde kullanılabilir) veya özel özel durum işleyicilerini çağırır.
  • Geliştirme dışı ortamlarda (örneğin ThrowOnBadRequest), Production varsayılan olarak false olur. Hatalı istek bağlama hataları, özel durum işleyicilerini atlayarak özel durum oluşturmadan doğrudan 400 Bad Request durum kodunu yazar.

JSON gövde bağlaması için, desteklenmeyen istek içerik türleri, 415 Unsupported Media Type415 olduğunda true değeri false olarak ayarlanmış bir ThrowOnBadRequest fırlatır veya 415 Unsupported Media TypeStatusCode olduğunda doğrudan BadHttpRequestException döndürür. Özel BindAsync uygulamalarından fırlatılan işlenmeyen özel durumlar, bu ayardan bağımsız olarak her zaman yayılır.

Hatalı istek bağlama hatalarının bir özel durum oluşturmasını ve yapılandırılan özel durum işleyicilerinizi tüm ortamlarda tetiklemesini sağlamak için ThrowOnBadRequestyapılandırın:

builder.Services.Configure<RouteHandlerOptions>(options =>
{
    options.ThrowOnBadRequest = true;
});

Important

ThrowOnBadRequest etkinleştirildiğinde, bağlama hataları bir BadHttpRequestException fırlatır. ASP.NET Core 11 ve sonraki sürümlerde, BadHttpRequestException.StatusCode varsayılan olarak sorun ayrıntıları yanıtlarında UseExceptionHandler öğesini korur. ASP.NET Core 10 ve önceki sürümlerde, işlenmeyen özel durumlar, işleyici hem BadHttpRequestException.StatusCode hem de oluşturulan 500 Internal Server Error üzerinde Status değerini açıkça korumadığı sürece varsayılan olarak HttpContext.Response.StatusCode olur. Yanıtı geçersiz kılan özel özel durum işleyicileri veya IExceptionHandler uygulamaları (ASP.NET Core 8 ve üzeri), istemci hatalarının sunucu hataları olarak raporlanmaması için BadHttpRequestException.StatusCode korunmasını yine de sağlamalıdır.

IProblemDetailsService geri dönüşü

Aşağıdaki kodda, httpContext.Response.WriteAsync("Fallback: An error occurred.") uygulaması bir IProblemDetailsService oluşturamıyorsa ProblemDetails 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:

Uyarı

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

  • application/json
  • application/problem+json
  • */* ve application/* gibi joker türleri

application/xml veya text/html gibi JSON olmayan medya türleri desteklenmemektedir ve geri dönüş davranışını tetikler.

Aşağıdaki örnek, Status Code Pages middleware öğ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);

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

TypedResults ile birden çok sonuç türü döndürme

Uç noktalar genellikle istek sonucuna bağlı olarak farklı sonuç türleri döndürür; örneğin, hata durumunda ProblemHttpResult veya başarı durumunda RedirectHttpResult döndürür. Derleme zamanı türü güvenliğini ve kesin olarak belirlenmiş imzaları korumak için, Results<TResult1,TResult2> ile TypedResults birleşim dönüş türünü kullanın. RedirectHttpResult gibi sonuç türleri OpenAPI meta verilerini otomatik olarak sağlamadığından, açık yanıt meta verilerini ProducesProblem ve Produces ile yapılandırın:

using Microsoft.AspNetCore.Http.HttpResults;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

bool IsSupportedProvider(string provider) => provider is "google" or "github";

app.MapGet("/login-provider",
    Results<RedirectHttpResult, ProblemHttpResult> (string? provider) =>
{
    if (string.IsNullOrEmpty(provider))
    {
        return TypedResults.Problem(
            title: "Provider not specified",
            detail: "A login provider is required.",
            statusCode: StatusCodes.Status400BadRequest);
    }

    if (!IsSupportedProvider(provider))
    {
        return TypedResults.Problem(
            title: "Provider not supported",
            detail: $"The provider '{provider}' is not supported.",
            statusCode: StatusCodes.Status400BadRequest);
    }

    return TypedResults.Redirect($"/auth/{provider}");
})
.Produces(StatusCodes.Status302Found)
.ProducesProblem(StatusCodes.Status400BadRequest);

app.Run();

TypedResults ile Results<TResult1,TResult2> kullanmak, beklenen iş hataları için özel durum oluşturmayı önler ve test edilebilirlik için kesin olarak belirlenmiş yanıt imzaları sağlar.

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.