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

Bu makalede, denetleyici tabanlı ASP.NET Core web API'lerinde hataların nasıl işleneceğini ve hata işlemenin nasıl özelleştirileceği açıklanır. En düşük API'lerde hata işleme hakkında bilgi için bkz . ASP.NET Core'daki hataları işleme ve Minimum API'lerdeki 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'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:

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

• 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 İşleme Ara Yazılımını kullanın:

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 trueayarlayınIgnoreApi. 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.

Özel Durum İşleme Ara Yazılımı, tüm ortamlarda tutarlı bir yük biçimi oluşturmak için Geliştirme ortamında da kullanılabilir:

1. içinde Program.cs, ortama özgü Özel Durum İşleme Ara Yazılım örneklerini kaydedin:

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   Yukarıdaki kodda ara yazılım şu şekilde kaydedilir:

   • Geliştirme ortamındaki bir yolu /error-development .
   • Geliştirme dışı ortamlardaki bir yolu /error .

2. Hem Geliştirme hem de Geliştirme dışı yollar için denetleyici eylemleri ekleyin:

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

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

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

İstemci hatası yanıtı

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, ancak hata yanıtları aşağıdaki yollardan biriyle yapılandırılabilir:

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

Varsayılan sorun ayrıntıları yanıtı

Aşağıdaki Program.cs dosya, API denetleyicileri için web uygulaması şablonları tarafından oluşturulmuştur:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Giriş geçersiz olduğunda döndüren BadRequest aşağıdaki denetleyiciyi 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:

• Uç /api/values2/divide nokta sıfır payda ile çağrılır.
• Uç /api/values2/squareroot nokta, sıfırdan küçük bir radik ve ile çağrılır.

Varsayılan sorun ayrıntıları yanıt gövdesinde aşağıdaki type, titleve status değerleri bulunur:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Sorun ayrıntıları hizmeti

ASP.NET Core, kullanarak IProblemDetailsServiceHTTP API'leri için Sorun Ayrıntıları oluşturmayı destekler. Daha fazla bilgi için Sorun ayrıntıları hizmetine bakın.

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.

SuppressMapClientErrors özelliği true olarak ayarlandığında hata durum kodları için otomatik bir ProblemDetails oluşturma devre dışı bırakılır:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Önceki kodu kullanarak, bir API denetleyicisi döndürdüğünde BadRequestyanıt gövdesi olmayan bir HTTP 400 yanıt durumu döndürülür. SuppressMapClientErrorsProblemDetails API Denetleyicisi uç noktası çağrılsa WriteAsync bile yanıtın oluşturulmasını engeller. WriteAsync bu makalenin devamında açıklanmıştır.

Sonraki bölümde, daha yararlı bir yanıt döndürmek için kullanarak CustomizeProblemDetailssorunun ayrıntılarının yanıt gövdesinin nasıl özelleştirileceği gösterilmektedir. Daha fazla özelleştirme seçeneği için bkz . Sorun ayrıntılarını özelleştirme.

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

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

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

Güncelleştirilmiş API denetleyicisi:

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }

}

Aşağıdaki kod, önceki örnekle birlikte kullanılan ve MathErrorTypekodunu içerirMathErrorFeature:

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

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

• Uç /divide nokta sıfır payda ile çağrılır.
• Uç /squareroot nokta, sıfırdan küçük bir radik ve ile çağrılır.
• URI'nin eşleşen uç noktası yok.

Sorun ayrıntıları yanıt gövdesi, uç noktalardan biri squareroot radik ve sıfırdan küçük olarak çağrıldığında aşağıdakileri içerir:

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

Örnek kodu görüntüleme veya indirme

Araç ProblemDetailsFactory

MVC, ve ValidationProblemDetails'nin ProblemDetails tüm örneklerini üretmek için kullanırMicrosoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory. 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ı ProblemDetailsFactory Program.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 kaynaklar

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