Control de errores en las API de ASP.NET Core

Nota:

Esta no es la versión más reciente de este artículo. Para obtener la versión actual, consulte la versión .NET 11 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulte la Política de soporte de .NET y .NET Core. Para la versión actual, consulte la versión .NET 10 de este artículo.

En este artículo se describe cómo controlar los errores en las API de ASP.NET Core. Se ha seleccionado la documentación de las API mínimas. Para ver la documentación de las API basadas en controladores, seleccione la pestaña Controllers. Para obtener instrucciones de control de errores de Blazor, consulte Handle errors in ASP.NET Core Blazor apps.

Página de Excepción del Desarrollador

En la Página de excepciones para el desarrollador se muestra información detallada sobre las excepciones de la solicitud no controladas. Usa DeveloperExceptionPageMiddleware para capturar excepciones sincrónicas y asincrónicas de la canalización HTTP y para generar respuestas de error. La página de excepciones del desarrollador se ejecuta al principio de la canalización del middleware, de modo que puede capturar las excepciones no controladas que se producen en el middleware que sigue.

Las aplicaciones de ASP.NET Core habilitan la página de excepciones para desarrolladores de forma predeterminada cuando se cumplen ambas condiciones:

Las aplicaciones creadas con plantillas anteriores, es decir, con WebHost.CreateDefaultBuilder, pueden habilitar la página de excepciones del desarrollador llamando a app.UseDeveloperExceptionPage.

Advertencia

No habilite la página de excepciones del desarrollador a menos que la aplicación se ejecute en el Development entorno. No comparta información detallada de excepciones públicamente cuando la aplicación se ejecute en producción. Para obtener más información sobre cómo configurar entornos, consulte ASP.NET Core entornos en tiempo de ejecución.

La página Excepción del desarrollador puede incluir la siguiente información sobre la excepción y la solicitud:

  • Seguimiento de pila
  • Parámetros de cadena de consulta, si los hay
  • Cookies, si existe
  • Headers
  • Metadatos del punto de conexión, si los hay

No se garantiza que la página excepción del desarrollador proporcione ninguna información. Usa el registro para obtener información completa del error.

En la imagen siguiente se muestra una página de excepción de desarrollador de ejemplo con animación para mostrar las pestañas y la información mostrada:

Página de excepciones del desarrollador animada para mostrar cada pestaña seleccionada.

En respuesta a una solicitud con un encabezado Accept: text/plain, la página de excepciones del desarrollador devuelve texto sin formato en lugar de HTML. Por ejemplo:

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

Para ver la Página de Excepciones del Desarrollador en una API mínima:

  • Ejecute la aplicación de ejemplo en el Development entorno.
  • Vaya al punto de conexión de /exception.

En esta sección se hace referencia a la siguiente aplicación de ejemplo para mostrar formas de controlar excepciones en una API mínima. Produce una excepción cuando se solicita el punto de conexión /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();

Controlador de excepciones

En entornos que no sean de desarrollo, utiliza el middleware de administración de excepciones para generar una carga útil de error.

Para configurar el exception handler middleware, llame a UseExceptionHandler. Por ejemplo, el código siguiente cambia la aplicación para responder con una carga compatible con RFC 7807 al cliente. Para obtener más información, consulte la sección Detalles del problema más adelante en este artículo.

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

Respuestas de error de cliente y servidor

Tenga en cuenta la siguiente aplicación de API mínima.

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

El extremo /users produce 200 OK con una representación json de User cuando id es mayor que 0; en caso contrario, un código de estado 400 BAD REQUEST sin cuerpo de respuesta. Para obtener más información sobre cómo crear una respuesta, consulte Creación de respuestas en aplicaciones de API mínimas.

Status Code Pages middleware se puede configurar para generar un contenido de cuerpo común, cuando está vacío, para todas las respuestas de cliente HTTP () o servidor (400-499500 -599). El middleware se configura llamando al método de extensión UseStatusCodePages .

Por ejemplo, en el ejemplo siguiente se cambia la aplicación para responder con una carga compatible con RFC 7807 al cliente para todas las respuestas de cliente y servidor, incluidos los errores de enrutamiento (por ejemplo, 404 NOT FOUND). Para obtener más información, consulte la sección Detalles del problema .

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

Detalles del problema

Los detalles del problema no son el único formato de respuesta para describir un error de API HTTP; sin embargo, normalmente se usan para notificar errores para las API HTTP.

El servicio de detalles del problema implementa la interfaz IProblemDetailsService, que admite la creación de detalles del problema en ASP.NET Core. El método de extensión AddProblemDetails(IServiceCollection) de IServiceCollection registra la implementación IProblemDetailsService predeterminada.

En aplicaciones de ASP.NET Core, el middleware siguiente genera respuestas HTTP de detalles del problema cuando se llama a AddProblemDetails, excepto cuando el encabezado HTTP de solicitud Accept no incluye uno de los tipos de contenido admitidos por el IProblemDetailsWriter registrado (valor predeterminado: application/json):

Las aplicaciones de API mínimas se pueden configurar para generar respuestas con detalles del problema para todas las respuestas de error HTTP del cliente y del servidor que aún no tienen contenido en el cuerpo mediante el método de extensión AddProblemDetails.

El código siguiente configura la aplicación para generar detalles del problema:

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

Para obtener más información sobre cómo usar AddProblemDetails, consulte Detalles del problema

Personalización del control de solicitudes incorrectas con RouteHandlerOptions.ThrowOnBadRequest

Cuando el enlace de parámetros de API mínimas detecta errores de solicitud incorrecta (como JSON con formato incorrecto o errores de conversión de tipos), el control de errores se rige por ThrowOnBadRequest:

  • En el entorno Development, el valor predeterminado de ThrowOnBadRequest es true. Los errores de enlace por solicitud incorrecta producen una excepción BadHttpRequestException, que pasa por el middleware de control de excepciones (UseExceptionHandler) e invoca los controladores IExceptionHandler registrados (disponibles en ASP.NET Core 8 y versiones posteriores) o los controladores de excepciones personalizados para generar respuestas de detalles del problema.
  • En entornos que no son de desarrollo (como Production), ThrowOnBadRequest tiene como valor predeterminado false. Los errores de enlace por solicitud incorrecta escriben un código de estado 400 Bad Request directamente sin producir ninguna excepción, lo que omite los controladores de excepciones personalizados.

En el caso del enlace del cuerpo JSON, los tipos de contenido de solicitud no admitidos generan una 415 Unsupported Media Type con false establecido en true cuando ThrowOnBadRequest es StatusCode o devuelven 415 directamente cuando es BadHttpRequestException. Las excepciones no controladas producidas desde implementaciones personalizadas BindAsync siempre se propagan independientemente de esta configuración.

Para asegurarse de que los errores de enlace por solicitud incorrecta producen una excepción y desencadenan los controladores de excepciones configurados en todos los entornos, configure ThrowOnBadRequest:

builder.Services.Configure<RouteHandlerOptions>(options =>
{
    options.ThrowOnBadRequest = true;
});

Important

Cuando ThrowOnBadRequest está habilitado, los errores de enlace producen una excepción BadHttpRequestException. En ASP.NET Core 11 y versiones posteriores, UseExceptionHandler conserva BadHttpRequestException.StatusCode de forma predeterminada en las respuestas de detalles del problema. En ASP.NET Core 10 y versiones anteriores, las excepciones no controladas se establecen de forma predeterminada en 500 Internal Server Error a menos que el controlador conserve BadHttpRequestException.StatusCode explícitamente tanto en HttpContext.Response.StatusCode como en el Status generado. Los controladores de excepciones personalizados o implementaciones de IExceptionHandler (ASP.NET Core 8 y versiones posteriores) que sobrescriben la respuesta deben seguir asegurándose de que se conserve BadHttpRequestException.StatusCode para que los errores de cliente no se notifiquen como errores de servidor.

Alternativa de IProblemDetailsService

En el código siguiente, httpContext.Response.WriteAsync("Fallback: An error occurred.") devuelve un error si la IProblemDetailsService implementación no puede generar un 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();

El código anterior:

Nota:

DefaultProblemDetailsWriter admite los siguientes tipos de contenido en el encabezado de la solicitud Accept:

  • application/json
  • application/problem+json
  • Tipos comodín, como */* y application/*

Los tipos de medios que no son JSON, como application/xml o text/html, no se admiten y activan el comportamiento alternativo.

El ejemplo siguiente es similar al anterior, excepto que llama 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);

Características adicionales de control de errores

Migración de controladores a API mínimas

Si va a migrar de api basadas en controlador a API mínimas:

  1. Reemplazar filtros de acción por filtros de punto de conexión o middleware
  2. Sustituya la validación del modelo por validación manual o enlace personalizado
  3. Reemplazar filtros de excepción por middleware de control de excepciones
  4. Configuración de los detalles del problema mediante AddProblemDetails() para respuestas de error coherentes

Cuándo usar el control de errores basado en el controlador

Considere la posibilidad de usar las API basadas en controlador si necesita:

  • Escenarios de validación de modelos complejos
  • Control centralizado de excepciones en varios controladores
  • Control detallado sobre el formato de respuesta de error
  • Integración con características de MVC, como filtros y convenciones

Para obtener información detallada sobre el control de errores basado en el controlador, incluidos los errores de validación, la personalización de detalles del problema y los filtros de excepciones, consulte las secciones controladores .