ASP.NET Core API-k hibáinak kezelése

Megjegyzés:

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információt a .NET és a .NET Core támogatási szabályzatában talál. A jelen cikk .NET 9-es verzióját lásd az aktuális kiadásért .

Minimális API-k

Ez a cikk a ASP.NET Core API-k hibáinak kezelését ismerteti. A minimális API-k dokumentációja ki van választva. A vezérlőalapú API-k dokumentációjának megtekintéséhez válassza a Vezérlők lapot. A Blazor hibakezelési útmutatót a ASP.NET Core-alkalmazások Blazor hibáinak kezelése című témakörben talál.

Vezérlők

Ez a cikk a ASP.NET Core API-k hibáinak kezelését ismerteti. A vezérlőalapú API-k dokumentációja ki van választva. A Minimal API-k dokumentációjának megtekintéséhez válassza a Minimal API-k lapot. A Blazor hibakezelési útmutatót a ASP.NET Core-alkalmazások Blazor hibáinak kezelése című témakörben talál.

Fejlesztői kivétel lap

A Fejlesztői kivétel lap részletes információkat jelenít meg a nem kezelt kérelmek kivételeiről. A HTTP-folyamat szinkron és aszinkron kivételeinek rögzítésére és hibaválaszok létrehozására használja DeveloperExceptionPageMiddleware . A fejlesztői kivételoldal a köztes szoftver folyamatának korai szakaszában fut, hogy a következő köztes szoftverben megjelenő kezeletlen kivételeket észlelhesse.

ASP.NET Core-alkalmazások alapértelmezés szerint engedélyezik a fejlesztői kivételoldalt, ha mindkettő:

• Futtatás a fejlesztési környezetben.
• Az alkalmazás az aktuális sablonokkal, azaz a használatával WebApplication.CreateBuilderjött létre.

A korábbi sablonok használatával létrehozott alkalmazások, vagyis a használatával WebHost.CreateDefaultBuilder, hívással engedélyezhetik a fejlesztői kivételoldalt app.UseDeveloperExceptionPage.

Figyelmeztetés

Csak akkor engedélyezze a fejlesztői kivételoldalt, ha az alkalmazás a fejlesztői környezetben fut. Ne ossza meg nyilvánosan a részletes kivételadatokat, ha az alkalmazás éles környezetben fut. További információ a környezetek konfigurálásáról: ASP.NET Core futtatókörnyezetek.

A Fejlesztői kivétel lap a következő információkat tartalmazhatja a kivételről és a kérésről:

• Verem nyomkövetése
• Lekérdezési sztringparaméterek, ha vannak ilyenek
• Cookie-k, ha vannak ilyenek
• Fejlécek
• Végpont metaadatai, ha vannak ilyenek

A fejlesztői kivételoldal nem garantáltan biztosít semmilyen információt. A teljes hibainformációk naplózása .

Az alábbi képen egy minta fejlesztői kivétellap látható, amelyen animáció látható a lapok és a megjelenített információk megjelenítéséhez:

Egy fejlécet tartalmazó Accept: text/plain kérésre válaszul a Fejlesztői kivételoldal a HTML helyett egyszerű szöveget ad vissza. Például:

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

Minimális API-k

A Fejlesztői kivétel lap megjelenítése minimális API-ban:

• Futtassa a mintaalkalmazást a fejlesztési környezetben.
• Lépjen a /exception végpontra.

Ez a szakasz a következő mintaalkalmazásra hivatkozik, amely bemutatja a minimális API-k kivételeinek kezelésére vonatkozó módszereket. Kivételt jelez a végpont /exception kérése esetén:

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

Vezérlők

A fejlesztői kivételoldal megtekintése vezérlőalapú API-ban:

• Adja hozzá a következő vezérlőműveletet egy vezérlőalapú API-hoz. A művelet kivételt eredményez a végpont kérése esetén.

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• Futtassa az alkalmazást a fejlesztői környezetben.

• Lépjen a vezérlőművelet által meghatározott végpontra.

Kivételkezelő

Nem fejlesztési környezetekben a Exception Handler Middleware használatával hozzon létre hasznos adatokat.

Minimális API-k

A hívás konfigurálásához hívja meg a Exception Handler Middlewarekövetkezőt UseExceptionHandler: Az alábbi kód például úgy módosítja az alkalmazást, hogy egy RFC 7807-kompatibilis hasznos adattal válaszoljon az ügyfélnek. További információt a cikk későbbi, Probléma részletei szakaszában talál.

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

Vezérlők

1. A Program.cs helyen hívja meg a UseExceptionHandler-t az Exception Handling Middleware hozzáadásához.

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. Konfiguráljon egy vezérlőműveletet az /error útvonalra való reagáláshoz:

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

Az előző HandleError művelet egy RFC 7807-kompatibilis hasznos adatcsomagot küld az ügyfélnek.

Figyelmeztetés

Ne jelölje meg a hibakezelő műveleti metódust HTTP-metódusattribútumokkal, például HttpGet. Az explicit igék megakadályozzák, hogy egyes kérések elérjék a műveletmetódust.

A Swagger/OpenAPI-t használó webes API-k esetében jelölje meg a hibakezelő műveletet az [ApiExplorerSettings] attribútummal, és állítsa a tulajdonságát IgnoreApi a következőretrue: . Ez az attribútumkonfiguráció kizárja a hibakezelő műveletet az alkalmazás OpenAPI-specifikációjából:

[ApiExplorerSettings(IgnoreApi = true)]

Névtelen hozzáférés engedélyezése a metódushoz, ha a hitelesítés nélküli felhasználóknak látniuk kell a hibát.

Ügyfél- és kiszolgálóhiba-válaszok

Minimális API-k

Fontolja meg a következő Minimal API-alkalmazást.

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

A /users végpont azt 200 OKjson jelzi User , hogy mikor id nagyobb, mint 0a 400 BAD REQUEST választörzs nélküli állapotkód. A válaszok létrehozásáról további információt a Válaszok létrehozása a Minimal API-alkalmazásokban című témakörben talál.

A Status Code Pages middleware rendszer konfigurálható úgy, hogy az összes HTTP-ügyfélre () vagy kiszolgálóra (400-499500 -599) adott válasz esetén üres törzstartalmat állítsunk elő. A köztes szoftver a UseStatusCodePages bővítmény metódus meghívásával van konfigurálva.

Az alábbi példa például úgy módosítja az alkalmazást, hogy egy RFC 7807-kompatibilis hasznos adattal válaszoljon az ügyfélnek az összes ügyfél- és kiszolgálóválasz esetében, beleértve az útválasztási hibákat (például 404 NOT FOUND). További információkért tekintse meg a Probléma részletei szakaszt .

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

Vezérlők

Vezérlőalapú API-k esetén a hibaválasz az alábbi módok egyikével konfigurálható:

1. A probléma részleteinek szolgáltatás használata
2. A ProblemDetailsFactory implementálása
3. Az ApiBehaviorOptions.ClientErrorMapping használata

A hibaeredmény 400-as vagy újabb HTTP-állapotkóddal rendelkező eredményként van definiálva. Webes API-vezérlők esetén az MVC átalakít egy hibaeredményt egy ProblemDetails.

A hibaállapot-kódok automatikus létrehozása ProblemDetails alapértelmezés szerint engedélyezve van.

Probléma részletei

A probléma részletei nem az egyetlen válaszformátum a HTTP API-hibák leírásához, azonban gyakran használják őket a HTTP API-k hibáinak jelentésére.

A probléma részletei szolgáltatás implementálja a felületet, amely támogatja a IProblemDetailsService probléma részleteinek létrehozását a ASP.NET Core-ban. A AddProblemDetails(IServiceCollection) bővítménymetódus IServiceCollection regisztrálja az alapértelmezett IProblemDetailsService implementációt.

A ASP.NET Core-alkalmazásokban a következő köztes szoftver generálja a probléma részleteit HTTP-válaszok meghívásakorAddProblemDetails, kivéve, ha a Accept kérelem HTTP-fejléce nem tartalmazza a regisztrált IProblemDetailsWriter (alapértelmezett) által támogatott tartalomtípusokat: application/json

• ExceptionHandlerMiddleware: Probléma részleteit tartalmazó választ hoz létre, ha nincs definiálva egyéni kezelő.
• StatusCodePagesMiddleware: Alapértelmezés szerint létrehoz egy probléma részleteit tartalmazó választ.
• DeveloperExceptionPageMiddleware: Probléma részleteit tartalmazó választ hoz létre a fejlesztés során, ha a kérelem HTTP-fejléce nem tartalmazza Accepta text/html következőt: .

Minimális API-k

Minimális API-alkalmazások konfigurálhatók úgy, hogy a bővítménymetódus használatával probléma részleteire adott választ generáljanak az összes OLYAN HTTP-ügyfél- és kiszolgálóhiba-válaszhoz, .

Az alábbi kód konfigurálja az alkalmazást a probléma részleteinek létrehozásához:

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

További információ a használatról AddProblemDetails: Probléma részletei

IProblemDetailsService tartalék

A következő kód egy hibát ad vissza, httpContext.Response.WriteAsync("Fallback: An error occurred.") ha a IProblemDetailsService megvalósítás nem tud létrehozni egy ProblemDetails:

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

Az előző kód:

• Hibaüzenetet ír a tartalék kóddal, ha a problemDetailsService rendszer nem tud írni egy ProblemDetails. Például egy végpont, ahol az Elfogadás kérelem fejléce olyan médiatípust határoz meg, amelyet a DefaulProblemDetailsWriter rendszer nem támogat.
• A Exception Handler Middleware-t használja.

A következő minta az előzőhöz hasonló, azzal a kivételt leszámítva, hogy meghívja a Status Code Pages middleware.

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

Vezérlők

Probléma részletei szolgáltatás

ASP.NET Core támogatja a HTTP API-k probléma részleteinek létrehozását a IProblemDetailsService.

Az alábbi kód úgy konfigurálja az alkalmazást, hogy probléma részleteit adja meg az összes olyan HTTP-ügyfél- és kiszolgálóhiba-válaszhoz, amely még nem rendelkezik törzstartalommal:

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

Vegye figyelembe az előző szakaszban szereplő API-vezérlőt, amely akkor ad vissza BadRequest , ha a bemenet érvénytelen:

[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 probléma részleteire adott válasz az előző kóddal jön létre, ha az alábbi feltételek bármelyike érvényes:

• A rendszer érvénytelen bemenetet ad meg.
• Az URI-nak nincs egyező végpontja.
• Nem kezelt kivétel történik.

A probléma részleteinek testreszabása a CustomizeProblemDetails

A beállításhoz ProblemDetailsOptionsa következő kód szolgálCustomizeProblemDetails:

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

Megvalósít ProblemDetailsFactory

Az MVC az Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory és ProblemDetailsValidationProblemDetailsa . Ezt a gyárat a következő célokra használják:

• Ügyfélhiba-válaszok
• Érvényesítési hibaválaszok
• ControllerBase.Problem és ControllerBase.ValidationProblem

A probléma részleteire adott válasz testreszabásához regisztráljon egy egyéni implementációt a ProblemDetailsFactory következő helyen Program.cs:

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

Használja a következő parancsot: ApiBehaviorOptions.ClientErrorMapping

ClientErrorMapping A tulajdonság használatával konfigurálhatja a ProblemDetails válasz tartalmát. A következő kód Program.cs például frissíti a tulajdonságot a Link 404 válaszhoz:

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

További hibakezelési funkciók

Minimális API-k

Migrálás vezérlőkről minimális API-kra

Ha a vezérlőalapú API-król minimális API-kra migrál:

1. Műveletszűrők cseréje végpontszűrőkre vagy köztes szoftverre
2. Modellérvényesítés cseréje manuális érvényesítésre vagy egyéni kötésre
3. Kivételszűrők cseréje a köztes szoftver kivételkezelésére
4. Probléma részleteinek konfigurálása konzisztens hibaválaszok használatával AddProblemDetails()

Mikor érdemes vezérlőalapú hibakezelést használni?

Szükség esetén fontolja meg a vezérlőalapú API-kat:

• Összetett modellérvényesítési forgatókönyvek
• Központosított kivételkezelés több vezérlő között
• A hibaválasz formázásának részletes szabályozása
• Integráció MVC-funkciókkal, például szűrőkkel és konvenciókkal

A vezérlőalapú hibakezeléssel kapcsolatos részletes információkért, beleértve az érvényesítési hibákat, a probléma részleteinek testreszabását és a kivételszűrőket, tekintse meg a Vezérlők lap szakaszait.

Vezérlők

Érvényesítési hiba válasza

Webes API-vezérlők esetén az MVC választípussal ValidationProblemDetails válaszol, ha a modell érvényesítése sikertelen. Az MVC az eredmények InvalidModelStateResponseFactory alapján hozza létre a hibaválaszt egy érvényesítési hiba esetén. Az alábbi példa az alapértelmezett gyárat egy olyan implementációra cseréli, amely XML-ként is támogatja a válaszok formázását a következőben Program.cs:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

Kivételek használata a válasz módosításához

A válasz tartalma a vezérlőn kívülről módosítható egy egyéni kivétel és egy műveletszűrő használatával:

1. Hozzon létre egy jól ismert kivételtípust:HttpResponseException

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. Hozzon létre egy műveletszűrőt:HttpResponseExceptionFilter

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

   Az előző szűrő a maximális egész szám mínusz 10 értékét adja meg Order . Ez Order lehetővé teszi a többi szűrő futtatását a folyamat végén.

3. Adja Program.cshozzá a műveletszűrőt a szűrők gyűjteményéhez:

   builder.Services.AddControllers(options =>
   {
       options.Filters.Add<HttpResponseExceptionFilter>();
   });
   

A vezérlők főbb eltérései

• Automatikus modellérvényesítés: A vezérlők automatikusan ellenőrzik a modell állapotát, és válaszokat adnak vissza 400 Bad Request az érvényesítési hibákra
• Kivételszűrők: Műveletszűrők és kivételszűrők használata központosított hibakezeléshez
• Beépített probléma részletei: Szabványosított hibaválaszok konfigurálása ApiBehaviorOptions
• Egyéni hibaválaszok: Felülbírálás InvalidModelStateResponseFactory egyéni érvényesítési hibaformázás esetén

További erőforrások

• A ModelState-ellenőrzés használata a ASP.NET Core Web API-ban
• Mintakód megtekintése vagy letöltése
• Hellang.Middleware.ProblemDetails