Minimum API uygulamalarında hataları işleme

Makale
11/06/2024

Not

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

Uyarı

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

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

David Acker'ın katkılarıyla

Bu makalede, En Düşük API uygulamalarında hataların nasıl işleneceğini açıklanmaktadır. Denetleyici tabanlı API'lerde hata işleme hakkında bilgi için bkz . ASP.NET Core'daki hataları işleme ve ASP.NET Core denetleyici tabanlı web API'lerinde hataları işleme.

Özel durumlar

Minimal API uygulamasında, işlenmeyen özel durumları işlemek için iki farklı yerleşik merkezi mekanizma vardır:

Geliştirici Özel Durum Sayfası ara yazılımı (Yalnızca Geliştirme ortamında kullanım için.)
Özel durum işleyici ara yazılımı

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

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'da birden çok ortam kullanma.

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
Üst Bilgiler
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:

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

Geliştirici Özel Durum Sayfasını görmek için:

Örnek uygulamayı Geliştirme ortamında çalıştırın.
/exception 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ı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();

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

Uç /users nokta json 200 OK, ne zaman id değerinin değerinden 0User 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 (500599- -400499) 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ı (örneğin, 404 NOT FOUND) dahil olmak üzere 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);

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, istek HTTP üst bilgisinin kayıtlı tarafından desteklenen içerik türlerinden birini içermemesiAccept dışında, aşağıdaki ara yazılım çağrıldığında AddProblemDetails sorun ayrıntıları HTTP yanıtları oluşturur (varsayılan: application/json):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 Accept text/htmlgeliştirme aşamasında bir sorun ayrıntıları yanıtı oluşturur.

Uzantı yöntemi kullanılarak AddProblemDetails henüz 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 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();

Yukarıdaki 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);

Bu makalede, En Düşük API uygulamalarında hataların nasıl işleneceğini açıklanmaktadır.

Özel durumlar

Minimal API uygulamasında, işlenmeyen özel durumları işlemek için iki farklı yerleşik merkezi mekanizma vardır:

Geliştirici Özel Durum Sayfası ara yazılımı (Yalnızca Geliştirme ortamında kullanım için.)
Özel durum işleyici ara yazılımı

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

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

app.Map("/exception", () 
    => { throw new InvalidOperationException("Sample Exception"); });

app.Run();

Geliştirici Özel Durum Sayfası

Geliştirici Özel Durum Sayfası, sunucu hataları için ayrıntılı yığın izlemelerini gösterir. HTTP işlem hattından zaman uyumlu ve zaman uyumsuz özel durumları yakalamak ve hata yanıtları oluşturmak için kullanır DeveloperExceptionPageMiddleware .

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 WebApplication.CreateBuilder kullanıyor.

Ara yazılımı yapılandırma hakkında daha fazla bilgi için bkz . Minimal API uygulamalarında ara yazılım.

Yukarıdaki Minimal API uygulamasını kullanarak, işlenmeyen Developer Exception Page bir özel durum algıladığında, aşağıdaki örneğe benzer bir varsayılan düz metin yanıtı oluşturur:

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain; charset=utf-8
Date: Thu, 27 Oct 2022 18:00:59 GMT
Server: Kestrel
Transfer-Encoding: chunked

    System.InvalidOperationException: Sample Exception
    at Program.<>c.<<Main>$>b__0_1() in ....:line 17
    at lambda_method2(Closure, Object, HttpContext)
    at Microsoft.AspNetCore.Routing.EndpointMiddleware.Invoke(HttpContext httpContext)
    --- End of stack trace from previous location ---
    at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)
HEADERS
=======
Accept: */*
Connection: keep-alive
Host: localhost:5239
Accept-Encoding: gzip, deflate, br

Uyarı

Özel durum işleyicisi

Ö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 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.Map("/exception", () 
    => { throw new InvalidOperationException("Sample 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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.Run();

public record User(int Id);

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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

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.

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 Accept text/htmlgeliştirme aşamasında bir sorun ayrıntıları yanıtı oluşturur.

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.Map("/users/{id:int}", (int id) 
    => id <= 0 ? Results.BadRequest() : Results.Ok(new User(id)) );

app.Map("/exception", () 
    => { throw new InvalidOperationException("Sample Exception"); });

app.Run();

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

Aracılığıyla paylaş

Minimum API uygulamalarında hataları işleme

Özel durumlar

Geliştirici Özel Durum Sayfası

Özel durum işleyicisi

İstemci ve Sunucu hata yanıtları

Sorun ayrıntıları

IProblemDetailsService geri dönüşü

Özel durumlar

Geliştirici Özel Durum Sayfası

Özel durum işleyicisi

İstemci ve Sunucu hata yanıtları

Sorun ayrıntıları

Ek kaynaklar