Jak obsługiwać błędy w minimalnych aplikacjach interfejsu API

Z udziałem DavidA Ackera

W tym artykule opisano sposób obsługi błędów w minimalnych aplikacjach interfejsu API. Aby uzyskać informacje na temat obsługi błędów w interfejsach API opartych na kontrolerach, zobacz Obsługa błędów w interfejsach ASP.NET Core i Obsługa błędów w internetowych interfejsach API opartych na kontrolerze ASP.NET Core.

Wyjątki

W minimalnej aplikacji interfejsu API istnieją dwa różne wbudowane mechanizmy scentralizowane do obsługi nieobsługiwane wyjątki:

• Oprogramowanie pośredniczące strony wyjątku dla deweloperów (tylko do użycia w środowisku dewelopera).
• Oprogramowanie pośredniczące obsługi wyjątków

W tej sekcji opisano następującą przykładową aplikację, aby zademonstrować sposoby obsługi wyjątków w minimalnym interfejsie API. Zgłasza wyjątek w przypadku żądania punktu końcowego /exception :

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

Strona wyjątku dla deweloperów

Na stronie wyjątku dewelopera są wyświetlane szczegółowe informacje o nieobsługiwanych wyjątkach żądań. Używa DeveloperExceptionPageMiddleware go do przechwytywania synchronicznych i asynchronicznych wyjątków z potoku HTTP i generowania odpowiedzi o błędach. Strona wyjątku dla deweloperów jest uruchamiana na wczesnym etapie potoku oprogramowania pośredniczącego, dzięki czemu może przechwytywać nieobsługiwane wyjątki zgłaszane w następujący sposób oprogramowania pośredniczącego.

aplikacje ASP.NET Core domyślnie włączają stronę wyjątku dla deweloperów, gdy obie te aplikacje:

• Uruchamianie w środowisku programistycznym.
• Aplikacja została utworzona przy użyciu bieżących szablonów, czyli przy użyciu polecenia WebApplication.CreateBuilder.

Aplikacje utworzone przy użyciu wcześniejszych szablonów, czyli przy użyciu metody WebHost.CreateDefaultBuilder, mogą włączyć stronę wyjątku dla deweloperów, wywołując metodę app.UseDeveloperExceptionPage.

Ostrzeżenie

Nie włączaj strony wyjątku dla deweloperów, chyba że aplikacja jest uruchomiona w środowisku dewelopera. Nie udostępniaj publicznie szczegółowych informacji o wyjątkach, gdy aplikacja działa w środowisku produkcyjnym. Aby uzyskać więcej informacji na temat konfigurowania środowisk, zobacz Używanie wielu środowisk w programie ASP.NET Core.

Strona wyjątku dewelopera może zawierać następujące informacje o wyjątku i żądaniu:

• Ślad stosu
• Parametry ciągu zapytania, jeśli istnieją
• Pliki cookie, jeśli istnieją
• Nagłówki
• Metadane punktu końcowego, jeśli istnieją

Strona wyjątku dla deweloperów nie jest gwarantowana, aby podać żadne informacje. Użyj rejestrowania , aby uzyskać pełne informacje o błędzie.

Na poniższej ilustracji przedstawiono przykładową stronę wyjątku dla deweloperów z animacją, aby wyświetlić karty i wyświetlane informacje:

W odpowiedzi na żądanie z nagłówkiem Accept: text/plain strona wyjątku dewelopera zwraca zwykły tekst zamiast HTML. Na przykład:

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

Aby wyświetlić stronę wyjątku dla deweloperów:

• Uruchom przykładową aplikację w środowisku deweloperów.
• Przejdź do punktu końcowego /exception .

Procedura obsługi wyjątków

W środowiskach nieprodukcyjnych użyj oprogramowania pośredniczącego obsługi wyjątków, aby wygenerować ładunek błędu. Aby skonfigurować metodę , wywołaj metodę Exception Handler MiddlewareUseExceptionHandler.

Na przykład poniższy kod zmienia aplikację w odpowiedzi na ładunek zgodny ze specyfikacją RFC 7807 do klienta. Aby uzyskać więcej informacji, zobacz sekcję Szczegóły problemu w dalszej części tego artykułu.

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

Odpowiedzi na błędy klienta i serwera

Rozważmy następującą minimalną aplikację interfejsu API.

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

Punkt /users końcowy tworzy 200 OK z reprezentacją User json wartości , gdy id jest większa niż 0, w przeciwnym razie 400 BAD REQUEST kod stanu bez treści odpowiedzi. Aby uzyskać więcej informacji na temat tworzenia odpowiedzi, zobacz Tworzenie odpowiedzi w minimalnych aplikacjach interfejsu API.

Można Status Code Pages middleware je skonfigurować tak, aby tworzyła wspólną zawartość treści, gdy jest pusta, dla wszystkich odpowiedzi klienta HTTP (499-400) lub serwera ().500 -599 Oprogramowanie pośredniczące jest konfigurowane przez wywołanie metody rozszerzenia UseStatusCodePages .

Na przykład w poniższym przykładzie aplikacja zmienia odpowiedź na ładunek zgodny ze specyfikacją RFC 7807 do klienta dla wszystkich odpowiedzi klienta i serwera, w tym błędy routingu (na przykład 404 NOT FOUND). Aby uzyskać więcej informacji, zobacz sekcję Szczegóły problemu.

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

Szczegóły problemu

Szczegóły problemu nie są jedynym formatem odpowiedzi opisujący błąd interfejsu API HTTP, jednak są one często używane do zgłaszania błędów dla interfejsów API HTTP.

Usługa szczegółów problemu IProblemDetailsService implementuje interfejs, który obsługuje tworzenie szczegółów problemu w ASP.NET Core. Metoda AddProblemDetails(IServiceCollection) rozszerzenia w systemie IServiceCollection rejestruje domyślną IProblemDetailsService implementację.

W aplikacjach ASP.NET Core następujące oprogramowanie pośredniczące generuje szczegóły problemów odpowiedzi HTTP podczas AddProblemDetails wywoływana, z wyjątkiem sytuacji, gdyAccept nagłówek HTTP żądania nie zawiera jednego z typów zawartości obsługiwanych przez zarejestrowane IProblemDetailsWriter (domyślnie: application/json):

• ExceptionHandlerMiddleware: generuje odpowiedź ze szczegółami problemu, gdy program obsługi niestandardowej nie jest zdefiniowany.
• StatusCodePagesMiddleware: domyślnie generuje odpowiedź ze szczegółami problemu.
• DeveloperExceptionPageMiddleware: generuje odpowiedź ze szczegółami problemu w programowania, gdy Accept nagłówek HTTP żądania nie zawiera text/htmlelementu .

Minimalne aplikacje interfejsu API można skonfigurować do generowania odpowiedzi na szczegóły problemu dla wszystkich odpowiedzi na błędy klienta HTTP i serwera, które nie mają jeszcze zawartości treści przy użyciu AddProblemDetails metody rozszerzenia.

Poniższy kod konfiguruje aplikację w celu wygenerowania szczegółów problemu:

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

Aby uzyskać więcej informacji na temat korzystania z programu AddProblemDetails, zobacz Szczegóły problemu

Rezerwowa usługa IProblemDetailsService

W poniższym kodzie zwraca błąd, httpContext.Response.WriteAsync("Fallback: An error occurred.") jeśli IProblemDetailsService implementacja nie może wygenerować elementu 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();

Powyższy kod ma następujące działanie:

• Zapisuje komunikat o błędzie z kodem rezerwowym, jeśli problemDetailsService program nie może napisać elementu ProblemDetails. Na przykład punkt końcowy, w którym nagłówek Akceptuj żądanie określa typ nośnika DefaulProblemDetailsWriter , który nie obsługuje.
• Używa oprogramowania pośredniczącego obsługi wyjątków.

Poniższy przykład jest podobny do powyższego z tą różnicą, że wywołuje metodę 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);