Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
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:
- Çalışma ortamında çalıştırılıyor
Development. - Uygulama, geçerli şablonlarla, yani kullanılarak WebApplication.CreateBuilderoluşturulmuştur.
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:
Ü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. -
/exceptionuç 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,
- 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 bilgisinde
Acceptbulunmadığında, geliştirme aşamasında bir sorun ayrıntıları yanıtı oluşturur.
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:
-
Developmentortamında,ThrowOnBadRequestvarsayılan olaraktrueolur. Hatalı istek bağlama hataları birUseExceptionHandleroluş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),Productionvarsayılan olarakfalseolur. Hatalı istek bağlama hataları, özel durum işleyicilerini atlayarak özel durum oluşturmadan doğrudan400 Bad Requestdurum 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:
-
problemDetailsService, birProblemDetailsyazamıyorsa geri dönüş koduyla bir hata iletisi yazar. Örneğin, Accept istek üst bilgisininDefaultProblemDetailsWritertarafından desteklenmeyen bir medya türünü belirttiği bir uç nokta. - Özel durum işleyici ara yazılımını kullanır.
Uyarı
, DefaultProblemDetailsWriter istek üst bilgisinde Accept aşağıdaki medya türlerini destekler:
application/jsonapplication/problem+json-
*/*veapplication/*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:
- Eylem filtrelerini uç nokta filtreleri veya ara yazılımla değiştirme
- Model doğrulamayı el ile doğrulama veya özel bağlama ile değiştirme
- Özel durum filtrelerini özel durum işleme ara yazılımıyla değiştirme
- 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.
İlgili içerik
ASP.NET Core