Control de errores en las API web basadas en el controlador de ASP.NET Core

En este artículo se describe cómo administrar errores y personalizar el control de errores con API web basadas en el controlador de ASP.NET Core. Para obtener información sobre el control de errores en las API mínimas, consulte Control de errores en ASP.NET Core and Control de errores en las API mínimas.

Página de excepciones para el 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.

De forma predeterminada, las aplicaciones de ASP.NET Core habilitan la página de excepciones del desarrollador cuando se cumplen las dos condiciones siguientes:

• Ejecutan en el entorno de desarrollo.
• La aplicación se creó con las plantillas actuales, es decir, con WebApplication.CreateBuilder.

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 para el desarrollador a menos que la aplicación se ejecute en el entorno de desarrollo. No comparta públicamente información detallada sobre las excepciones cuando la aplicación se ejecute en producción. Para más información sobre la configuración de los entornos, consulte Uso de varios entornos en ASP.NET Core.

La página de excepciones para el desarrollador puede incluir la siguiente información sobre la excepción y la solicitud:

• Seguimiento de la pila
• Parámetros de cadena de consulta (si existen)
• Cookies, si existen
• encabezados
• Metadatos del punto de conexión, si los hay

No se garantiza que la página de excepciones del desarrollador proporcione alguna información. Use el registro obtener información completa sobre el 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:

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:

• Agregue la siguiente acción de controlador a una API basada en el controlador. La acción produce una excepción cuando se solicita el punto de conexión.

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

• Ejecute la aplicación en el entorno de desarrollo.

• Vaya al punto de conexión definido por la acción del controlador.

Controlador de excepciones

En entornos que no son de desarrollo, use el middleware de control de excepciones para producir una carga de error:

1. En Program.cs, llame a UseExceptionHandler para agregar el middleware de control de excepciones:

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

2. Configure una acción de controlador para responder a la ruta /error:

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

La acción HandleError anterior envía una carga compatible con RFC 7807 al cliente.

Advertencia

No marque el método de acción del controlador de errores con atributos de método HTTP, como HttpGet. Los verbos explícitos impiden que algunas solicitudes lleguen al método de acción.

Para las API web que usan Swagger /OpenAPI, marque la acción del controlador de errores con el atributo [ApiExplorerSettings] y establezca su propiedad IgnoreApi en true. Esta configuración de atributo excluye la acción del controlador de errores de la especificación OpenAPI de la aplicación:

[ApiExplorerSettings(IgnoreApi = true)]

Permita el acceso anónimo al método si los usuarios no autenticados deben recibir el error.

El middleware de control de excepciones también se puede usar en el entorno de desarrollo para generar un formato de carga coherente en todos los entornos:

1. En Program.cs, registre las instancias de middleware de control de excepciones específicas del entorno:

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

   En el código anterior, el middleware se ha registrado con:

   • Una ruta de /error-development en el entorno de desarrollo.
   • Una ruta de /error en entornos que no son de desarrollo.

2. Agregue acciones de controlador tanto para las rutas de desarrollo como para las que no son de desarrollo:

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

Uso de excepciones para modificar la respuesta

El contenido de la respuesta se puede modificar desde fuera del controlador mediante una excepción personalizada y un filtro de acción:

1. Cree un tipo de excepción conocido denominado 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. Cree un filtro de acción denominado 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;
           }
       }
   }
   

   El filtro anterior especifica un Order del valor entero máximo menos 10. Este Order permite que otros filtros se ejecuten al final de la canalización.

3. En Program.cs, agregue el filtro de acción a la colección de filtros:

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

Respuesta de error ante errores de validación

En el caso de los controladores de API web, MVC responde con un tipo de respuesta ValidationProblemDetails cuando se produce un error en la validación del modelo. MVC usa los resultados de InvalidModelStateResponseFactory para construir la respuesta de error para un error de validación. El siguiente ejemplo reemplaza la fábrica predeterminada por una implementación que también es compatible con el formato de respuestas como XML, en 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();

Respuesta de error del cliente

Se define un resultado error como un resultado con un código de estado HTTP de 400 o superior. Para los controladores de la API web, MVC transforma un resultado de error para producir un ProblemDetails.

La creación automática de un ProblemDetails para los códigos de estado de error está habilitada de manera predeterminada, pero las respuestas de error pueden configurarse de una de las siguientes formas:

1. Usar el servicio de detalles del problema
2. Implementar ProblemDetailsFactory
3. Usar ApiBehaviorOptions.ClientErrorMapping

Respuesta de detalles del problema predeterminada

El siguiente archivo Program.cs fue generado por las plantillas de aplicación web para controladores de API:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Considere el controlador siguiente, que devuelve BadRequest cuando la entrada no es válida:

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

Se genera una respuesta de detalles del problema con el código anterior cuando se aplica cualquiera de las condiciones siguientes:

• Se llama al punto de conexión de /api/values2/divide con denominador cero.
• Se llama al punto de conexión de /api/values2/squareroot con un radicando menor que cero.

El cuerpo de la respuesta de detalles del problema predeterminado tiene los siguientes valores type, title y status:

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

Servicio de detalles del problema

ASP.NET Core admite la creación de detalles del problema para las API HTTP mediante IProblemDetailsService. Para más información, consulte el Servicio de detalles del problema.

El código siguiente configura la aplicación para generar una respuesta de detalles del problema para todas las respuestas de error de servidor y cliente HTTP que aún no tienen contenido en el cuerpo:

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

Considere el controlador de API de la sección anterior, que devuelve BadRequest cuando la entrada no es válida:

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

Se genera una respuesta de detalles del problema con el código anterior cuando se aplica cualquiera de las condiciones siguientes:

• Se proporciona una entrada no válida.
• El URI no tiene ningún punto de conexión coincidente.
• Se produce una excepción no controlada.

La creación automática de ProblemDetails para los códigos de estado de error está deshabilitada cuando la propiedad SuppressMapClientErrors está establecida en true:

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

Usando el código anterior, cuando un controlador de API devuelve BadRequest, se devuelve un estado de respuesta HTTP 400 sin cuerpo de respuesta. SuppressMapClientErrors evita que se cree una respuesta ProblemDetails, incluso cuando se llama a WriteAsync para un punto de conexión del controlador de API. WriteAsync se explica posteriormente en este artículo.

La siguiente sección muestra cómo personalizar el cuerpo de respuesta de los detalles del problema, usando CustomizeProblemDetails, para devolver una respuesta más útil. Para más opciones de personalización, consulte Personalización de los detalles del problema.

Personalización de los detalles del problema con CustomizeProblemDetails

El código siguiente usa ProblemDetailsOptions para establecer CustomizeProblemDetails:

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

El controlador de API actualizado:

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

}

El siguiente código contiene MathErrorFeature y MathErrorType, que se usan con el ejemplo anterior:

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

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

Se genera una respuesta de detalles del problema con el código anterior cuando se aplica cualquiera de las condiciones siguientes:

• Se llama al punto de conexión de /divide con denominador cero.
• Se llama al punto de conexión de /squareroot con un radicando menor que cero.
• El URI no tiene ningún punto de conexión coincidente.

El cuerpo de la respuesta de detalles del problema contiene lo siguiente cuando se llama a cualquiera de los puntos de conexión de squareroot con un radicando menor que cero:

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

Ver o descargar el código de ejemplo

Implemente ProblemDetailsFactory

MVC usa Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory para generar todas las instancias de ProblemDetails y ValidationProblemDetails. Esta fábrica se usa para:

• Respuestas de error del cliente
• Respuestas de error ante errores de validación
• ControllerBase.Problem y ControllerBase.ValidationProblem

Para personalizar la respuesta de detalles del problema, registre una implementación personalizada de ProblemDetailsFactory en Program.cs:

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

Use ApiBehaviorOptions.ClientErrorMapping

Use la propiedad ClientErrorMapping para configurar el contenido de la respuesta ProblemDetails. Por ejemplo, el código siguiente de Program.cs permite actualizar la propiedad Link para respuestas 404:

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

Recursos adicionales

• Cómo usar la validación ModelState en la API web de ASP.NET Core
• Ver o descargar el código de ejemplo
• Hellang.Middleware.ProblemDetails