Controlar errores en ASP.NET Core

Por Tom Dykstra

Este artículo trata sobre los métodos comunes para controlar errores en aplicaciones web ASP.NET Core. Consulta también Control de errores en las API web basadas en el controlador de ASP.NET Core y Control de errores en las API mínimas.

Para obtener instrucciones sobre el control de errores de Blazor, que agrega o reemplaza las instrucciones de este artículo, consulta Control de errores en aplicaciones de ASP.NET Core Blazor.

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 habilites la página de excepciones para el desarrollador a menos que la aplicación se ejecute en el entorno de desarrollo. No compartas públicamente información detallada sobre las excepciones cuando la aplicación se ejecute en producción. Para obtener más información sobre la configuración de los entornos, consulta 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. Usa 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

Página del controlador de excepciones

Para configurar una página de control de errores personalizada para el entorno de producción, llama a UseExceptionHandler. Este middleware de control de excepciones:

• Captura y registra las excepciones no controladas.
• Vuelve a ejecutar la solicitud en una canalización alternativa con la ruta de acceso indicada. La solicitud no se vuelve a ejecutar si se ha iniciado la respuesta. El código generado por la plantilla vuelve a ejecutar la solicitud mediante la ruta de acceso /Error.

Advertencia

Si la canalización alternativa produce una excepción propia, el middleware de control de excepciones vuelve a producir la excepción original.

Dado que este middleware puede volver a ejecutar la canalización de solicitudes:

• Los middleware deben controlar la reentrada con la misma solicitud. Normalmente, esto significa limpiar su estado después de llamar a _next o almacenar en caché su procesamiento en HttpContext para evitar volver a hacerlo. Al tratar con el cuerpo de la solicitud, esto significa almacenar en búfer o almacenar en caché los resultados como el lector de formularios.
• En el caso de la sobrecarga UseExceptionHandler(IApplicationBuilder, String) que se usa en las plantillas, solo se modifica la ruta de acceso de la solicitud y se borran los datos de ruta. Los datos de la solicitud, como los encabezados, los métodos y los elementos, se reutilizan tal cual.
• Los servicios con ámbito siguen siendo los mismos.

En el ejemplo siguiente, UseExceptionHandler agrega middleware de control de excepciones en entornos que no son de desarrollo:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

La plantilla de aplicación de Razor Pages proporciona una página de error (.cshtml) y una clase PageModel (ErrorModel) en la carpeta Pages. Para una aplicación de MVC, la plantilla de proyecto incluye un método de acción de Error y una vista del error para el controlador de Home.

El middleware de control de excepciones vuelve a ejecutar la solicitud mediante el método HTTP original. Si un punto de conexión de controlador de errores está restringido a un conjunto específico de métodos HTTP, solo se ejecuta para esos métodos HTTP. Por ejemplo, una acción de controlador de MVC que usa el atributo [HttpGet] solo se ejecuta para solicitudes GET. Para asegurarte de que todas las solicitudes lleguen a la página de control de errores personalizada, no las restrinja a un conjunto específico de métodos HTTP.

Para controlar las excepciones de manera diferente en función del método HTTP original:

• En el caso de Razor Pages, crea varios métodos de control. Por ejemplo, usa OnGet para controlar las excepciones GET y usa OnPost para controlar las excepciones POST.
• Para MVC, aplica los atributos de verbo HTTP a varias acciones. Por ejemplo, usa [HttpGet] para controlar las excepciones GET y usa [HttpPost] para controlar las excepciones POST.

Para permitir que los usuarios no autenticados vean la página de control de errores personalizada, asegúrate de que admite el acceso anónimo.

Acceso a la excepción

Use IExceptionHandlerPathFeature para acceder a la ruta de acceso de la solicitud original y a la excepción en un controlador de errores. En el ejemplo siguiente se usa IExceptionHandlerPathFeature para obtener más información sobre la excepción que se produjo:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
[IgnoreAntiforgeryToken]
public class ErrorModel : PageModel
{
    public string? RequestId { get; set; }

    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);

    public string? ExceptionMessage { get; set; }

    public void OnGet()
    {
        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;

        var exceptionHandlerPathFeature =
            HttpContext.Features.Get<IExceptionHandlerPathFeature>();

        if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
        {
            ExceptionMessage = "The file was not found.";
        }

        if (exceptionHandlerPathFeature?.Path == "/")
        {
            ExceptionMessage ??= string.Empty;
            ExceptionMessage += " Page: Home.";
        }
    }
}

Advertencia

No proporciones información de errores confidencial a los clientes. Proporcionar información de los errores es un riesgo para la seguridad.

Lambda del controlador de excepciones

Una alternativa a una página del controlador de excepciones personalizada es proporcionar una expresión lambda en UseExceptionHandler. Usar una expresión lambda permite acceder al error antes de devolver la respuesta.

En el código siguiente se usa una expresión lambda para el control de excepciones:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler(exceptionHandlerApp =>
    {
        exceptionHandlerApp.Run(async context =>
        {
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;

            // using static System.Net.Mime.MediaTypeNames;
            context.Response.ContentType = Text.Plain;

            await context.Response.WriteAsync("An exception was thrown.");

            var exceptionHandlerPathFeature =
                context.Features.Get<IExceptionHandlerPathFeature>();

            if (exceptionHandlerPathFeature?.Error is FileNotFoundException)
            {
                await context.Response.WriteAsync(" The file was not found.");
            }

            if (exceptionHandlerPathFeature?.Path == "/")
            {
                await context.Response.WriteAsync(" Page: Home.");
            }
        });
    });

    app.UseHsts();
}

Otra manera de usar una expresión lambda es establecer el código de estado en función del tipo de excepción, como en el ejemplo siguiente:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.UseExceptionHandler(new ExceptionHandlerOptions
    {
        StatusCodeSelector = ex => ex is TimeoutException
            ? StatusCodes.Status503ServiceUnavailable
            : StatusCodes.Status500InternalServerError
    });
}

Advertencia

No proporciones información de errores confidencial a los clientes. Proporcionar información de los errores es un riesgo para la seguridad.

IExceptionHandler

IExceptionHandler es una interfaz que proporciona al desarrollador una devolución de llamada para controlar excepciones conocidas en una ubicación central.

Las implementaciones de IExceptionHandler se registran mediante una llamada de IServiceCollection.AddExceptionHandler<T>. La duración de una instancia IExceptionHandler es singleton. Se pueden agregar varias implementaciones y se llaman en el orden registrado.

Si un controlador de excepciones controla una solicitud, puede devolver true para detener el procesamiento. Si un controlador de excepciones no controla una excepción, el control vuelve al comportamiento predeterminado y a las opciones del middleware. Se emiten diferentes métricas y registros para excepciones controladas frente a excepciones no controladas.

En el siguiente ejemplo se muestra una implementación de IExceptionHandler:

using Microsoft.AspNetCore.Diagnostics;

namespace ErrorHandlingSample
{
    public class CustomExceptionHandler : IExceptionHandler
    {
        private readonly ILogger<CustomExceptionHandler> logger;
        public CustomExceptionHandler(ILogger<CustomExceptionHandler> logger)
        {
            this.logger = logger;
        }
        public ValueTask<bool> TryHandleAsync(
            HttpContext httpContext,
            Exception exception,
            CancellationToken cancellationToken)
        {
            var exceptionMessage = exception.Message;
            logger.LogError(
                "Error Message: {exceptionMessage}, Time of occurrence {time}",
                exceptionMessage, DateTime.UtcNow);
            // Return false to continue with the default behavior
            // - or - return true to signal that this exception is handled
            return ValueTask.FromResult(false);
        }
    }
}

En el ejemplo siguiente se muestra cómo registrar una implementación de IExceptionHandler para la inserción de dependencias:

using ErrorHandlingSample;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddRazorPages();
builder.Services.AddExceptionHandler<CustomExceptionHandler>();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Remaining Program.cs code omitted for brevity

Cuando el código anterior se ejecuta en el entorno de desarrollo:

• Se llama primero al CustomExceptionHandler para controlar una excepción.
• Tras registrar la excepción, el método TryHandleAsync devuelve false, por lo que se muestra la página de excepción del desarrollador.

En otros entornos:

• Se llama primero al CustomExceptionHandler para controlar una excepción.
• Tras registrar la excepción, el método TryHandleAsync devuelve false, por lo que se muestra la página de /Error.

UseStatusCodePages

Una aplicación ASP.NET Core no proporciona de forma predeterminada ninguna página de códigos de estado para los códigos de estado HTTP, como 404 - No encontrado. Cuando la aplicación establece un código de estado de error HTTP 400-599 que no tiene un cuerpo, devuelve el código de estado y un cuerpo de respuesta vacío. Para habilitar los controladores de solo texto predeterminados para los códigos de estado de error comunes, llame a UseStatusCodePages en Program.cs:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePages();

Llame a UseStatusCodePages antes del middleware de control de solicitudes. Por ejemplo, llama a UseStatusCodePages antes del middleware de archivos estáticos y el middleware de puntos de conexión.

Cuando no se usa UseStatusCodePages, al navegar a una dirección URL sin punto de conexión se devuelve un mensaje de error dependiente del explorador que indica que no se encuentra el punto de conexión. Cuando se llama a UseStatusCodePages, el explorador devuelve la siguiente respuesta:

Status Code: 404; Not Found

UseStatusCodePages no se utiliza normalmente en producción, ya que devuelve un mensaje que no es útil para los usuarios.

Nota

El middleware de páginas de códigos de estado no detecta excepciones. Para proporcionar una página de control de errores personalizada, usa la página del controlador de excepciones.

UseStatusCodePages con cadena de formato

Para personalizar el texto y el tipo de contenido de la respuesta, usa la sobrecarga de UseStatusCodePages que adopta una cadena de tipo de contenido y formato:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// using static System.Net.Mime.MediaTypeNames;
app.UseStatusCodePages(Text.Plain, "Status Code Page: {0}");

En el código anterior, {0} es un marcador de posición para el código de error.

UseStatusCodePages con una cadena de formato no se utiliza normalmente en producción, ya que devuelve un mensaje que no es útil para los usuarios.

UseStatusCodePages con una expresión lambda

Para especificar el código de escritura de respuesta y control de errores personalizado, usa la sobrecarga de UseStatusCodePages que adopta una expresión lambda:

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePages(async statusCodeContext =>
{
    // using static System.Net.Mime.MediaTypeNames;
    statusCodeContext.HttpContext.Response.ContentType = Text.Plain;

    await statusCodeContext.HttpContext.Response.WriteAsync(
        $"Status Code Page: {statusCodeContext.HttpContext.Response.StatusCode}");
});

UseStatusCodePages con una expresión lambda no se utiliza normalmente en producción, ya que devuelve un mensaje que no es útil para los usuarios.

UseStatusCodePagesWithRedirects

Método de extensión UseStatusCodePagesWithRedirects:

• Envía un código de estado 302 - Encontrado al cliente.
• Redirige el cliente al punto de conexión de control de errores proporcionado en la plantilla de dirección URL. El punto de conexión de control de errores suele mostrar información de error y devuelve HTTP 200.

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithRedirects("/StatusCode/{0}");

La plantilla de dirección URL puede incluir un marcador de posición {0} para el código de estado, tal y como se muestra en el código anterior. Si la plantilla de dirección URL comienza con ~ (tilde), la ~ se sustituye por el elemento PathBase de la aplicación. Si especifica un punto de conexión en la aplicación, cree una vista de MVC o una página de Razor para ese punto de conexión.

Este método se usa normalmente cuando la aplicación:

• Debes redirigir al cliente a un punto de conexión diferente, normalmente en casos en los que una aplicación diferente procesa el error. En el caso de aplicaciones web, la barra de direcciones del explorador del cliente refleja el punto de conexión redirigido.
• No debes conservar ni devolver el código de estado original con la respuesta de redirección inicial.

UseStatusCodePagesWithReExecute

Método de extensión UseStatusCodePagesWithReExecute:

• Genera el cuerpo de respuesta, para lo cual vuelve a ejecutar la canalización de solicitud mediante una ruta de acceso alternativa.
• No modifica el código de estado antes o después de volver a ejecutar la canalización.

La nueva ejecución de canalización puede modificar el código de estado de la respuesta, ya que la nueva canalización tiene un control absoluto del código de estado. Si la nueva canalización no modifica el código de estado, se envía el código de estado original al cliente.

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseStatusCodePagesWithReExecute("/StatusCode/{0}");

Si se especifica un punto de conexión en la aplicación, cree una vista de MVC o una página de Razor para ese punto de conexión.

Este método se usa normalmente cuando la aplicación debe:

• Procesar la solicitud sin redirigirla a un punto de conexión diferente. En el caso de aplicaciones web, la barra de direcciones del explorador del cliente refleja el punto de conexión solicitado originalmente.
• Conservar y devolver el código de estado original con la respuesta.

La plantilla de dirección URL debe empezar con / y puede incluir un marcador de posición {0} para el código de estado. Para pasar el código de estado como un parámetro de cadena de consulta, pase un segundo argumento a UseStatusCodePagesWithReExecute. Por ejemplo:

var app = builder.Build();  
app.UseStatusCodePagesWithReExecute("/StatusCode", "?statusCode={0}");

El punto de conexión que procesa el error puede obtener la dirección URL original que generó el error, como se muestra en el ejemplo siguiente:

[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public class StatusCodeModel : PageModel
{
    public int OriginalStatusCode { get; set; }

    public string? OriginalPathAndQuery { get; set; }

    public void OnGet(int statusCode)
    {
        OriginalStatusCode = statusCode;

        var statusCodeReExecuteFeature =
            HttpContext.Features.Get<IStatusCodeReExecuteFeature>();

        if (statusCodeReExecuteFeature is not null)
        {
            OriginalPathAndQuery = $"{statusCodeReExecuteFeature.OriginalPathBase}"
                                    + $"{statusCodeReExecuteFeature.OriginalPath}"
                                    + $"{statusCodeReExecuteFeature.OriginalQueryString}";

        }
    }
}

Dado que este middleware puede volver a ejecutar la canalización de solicitudes:

• Los middleware deben controlar la reentrada con la misma solicitud. Normalmente, esto significa limpiar su estado después de llamar a _next o almacenar en caché su procesamiento en HttpContext para evitar volver a hacerlo. Al tratar con el cuerpo de la solicitud, esto significa almacenar en búfer o en caché los resultados como el lector de formularios.
• Los servicios con ámbito siguen siendo los mismos.

Deshabilitar las páginas de códigos de estado

Para deshabilitar las páginas de códigos de estado de un método de acción o controlador MVC, use el atributo [SkipStatusCodePages].

Para deshabilitar las páginas de códigos de estado de solicitudes específicas de un método de controlador de Razor Pages o un controlador MVC, use IStatusCodePagesFeature:

public void OnGet()
{
    var statusCodePagesFeature =
        HttpContext.Features.Get<IStatusCodePagesFeature>();

    if (statusCodePagesFeature is not null)
    {
        statusCodePagesFeature.Enabled = false;
    }
}

Código de control de excepciones

El código de las páginas de control de excepciones también puede iniciar excepciones. Las páginas de errores de producción se deben probar minuciosamente y se debe tener especial cuidado para evitar que inicien sus propias excepciones.

Encabezados de respuesta

Una vez enviados los encabezados de una respuesta:

• La aplicación no puede cambiar el código de estado de la respuesta.
• No se pueden ejecutar páginas o controladores de excepciones. Deberá completarse la respuesta o anularse la conexión.

Control de excepciones del servidor

Además de la lógica de control de excepciones de la aplicación, la implementación del servidor HTTP puede controlar algunas excepciones. Si el servidor almacena en caché una excepción antes de que se envíen los encabezados de respuesta, envía una respuesta 500 - Internal Server Error sin cuerpo. Si el servidor almacena en caché una excepción después de que se envían los encabezados de respuesta, cierra la conexión. El servidor controla las solicitudes que no controla la aplicación. El control de excepciones del servidor controla cualquier excepción que se produzca cuando el servidor controle la solicitud. Las páginas de error personalizadas, el middleware de control de excepciones y los filtros de la aplicación no afectan este comportamiento.

Control de excepciones de inicio

Solo el nivel de hospedaje puede controlar las excepciones que tienen lugar durante el inicio de la aplicación. El host puede configurarse para capturar errores de inicio y capturar errores detallados.

La capa de hospedaje puede mostrar una página de error para un error de inicio capturado solo si este se produce después del enlace de puerto/dirección del host. Si se produce un error de enlace:

• La capa de hospedaje registra una excepción crítica.
• El proceso de dotnet se bloquea.
• No se muestra ninguna página de error si el servidor HTTP es Kestrel.

Si se ejecuta en IIS, en Azure App Service o en IIS Express, el módulo ASP.NET Core devuelve un error de proceso 502.5 si el proceso no se puede iniciar. Para más información, consulte Solución de problemas de ASP.NET Core en Azure App Service e IIS.

Página de error de la base de datos

El filtro de excepciones AddDatabaseDeveloperPageExceptionFilter de la página del desarrollador de bases de datos captura las excepciones relacionadas con la base de datos que se pueden resolver mediante migraciones de Entity Framework Core. Cuando se producen estas excepciones, se genera una respuesta HTML con los detalles de las acciones posibles para resolver el problema. Esta página debe habilitarse solo en el entorno de desarrollo. El código siguiente agrega el filtro de la página de excepciones del desarrollador:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDatabaseDeveloperPageExceptionFilter();
builder.Services.AddRazorPages();

Filtros de excepciones

En las aplicaciones de MVC, los filtros de excepciones se pueden configurar globalmente, o bien por controlador o por acción. En las aplicaciones de Razor Pages, se pueden configurar a nivel global o por modelo de página. Estos filtros controlan todas las excepciones no controladas que se hayan producido durante la ejecución de una acción de controlador o de otro filtro. Para más información, consulte Filtros en ASP.NET Core.

Los filtros de excepciones son útiles para interceptar las excepciones que se producen en las acciones de MVC, pero no son tan flexibles como el middleware de control de excepciones integrado, UseExceptionHandler. Se recomienda usar UseExceptionHandler, a no ser que tenga que realizar el control de errores de otra forma según la acción de MVC elegida.

Errores de estado del modelo

Para obtener información sobre cómo controlar los errores de estado de los modelos, vea Enlace de modelos y Validación de modelos.

Detalles del problema

Los detalles del problema no son el único formato de respuesta para describir un error de la API HTTP; sin embargo, se usan normalmente 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):

• ExceptionHandlerMiddleware: genera una respuesta de detalles del problema cuando no se define un controlador personalizado.
• StatusCodePagesMiddleware: genera una respuesta de detalles del problema de forma predeterminada.
• DeveloperExceptionPageMiddleware: genera una respuesta de detalles del problema en el desarrollo cuando el encabezado HTTP de solicitud Accept no incluye text/html.

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:

builder.Services.AddProblemDetails();

var app = builder.Build();        

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseStatusCodePages();

En la sección siguiente se muestra cómo personalizar el cuerpo de la respuesta de detalles del problema.

Personalización de los detalles del problema

La creación automática de un objeto ProblemDetails se puede personalizar mediante las siguientes opciones:

1. Use ProblemDetailsOptions.CustomizeProblemDetails
2. Uso de una IProblemDetailsWriter personalizada
3. Llamada a IProblemDetailsService en un middleware

Operation de CustomizeProblemDetails:

Los detalles del problema generado se pueden personalizar mediante CustomizeProblemDetails, y las personalizaciones se aplican a todos los detalles del problema generados automáticamente.

El código siguiente usa ProblemDetailsOptions para establecer CustomizeProblemDetails:

builder.Services.AddProblemDetails(options =>
    options.CustomizeProblemDetails = ctx =>
            ctx.ProblemDetails.Extensions.Add("nodeId", Environment.MachineName));

var app = builder.Build();        

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseStatusCodePages();

Por ejemplo, un resultado del punto de conexión HTTP Status 400 Bad Request genera el siguiente cuerpo de respuesta de detalles del problema:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "nodeId": "my-machine-name"
}

IProblemDetailsWriter personalizado

Se puede crear una implementación de IProblemDetailsWriter para personalizaciones avanzadas.

public class SampleProblemDetailsWriter : IProblemDetailsWriter
{
    // Indicates that only responses with StatusCode == 400
    // are handled by this writer. All others are
    // handled by different registered writers if available.
    public bool CanWrite(ProblemDetailsContext context)
        => context.HttpContext.Response.StatusCode == 400;

    public ValueTask WriteAsync(ProblemDetailsContext context)
    {
        // Additional customizations.

        // Write to the response.
        var response = context.HttpContext.Response;
        return new ValueTask(response.WriteAsJsonAsync(context.ProblemDetails));
    }
}

Nota: Cuando se usa un elemento personalizado IProblemDetailsWriter, el elemento personalizado IProblemDetailsWriter se debe registrar antes de llamar a AddRazorPages, AddControllers, AddControllersWithViews o AddMvc:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTransient<IProblemDetailsWriter, SampleProblemDetailsWriter>();

var app = builder.Build();

// Middleware to handle writing problem details to the response.
app.Use(async (context, next) =>
{
    await next(context);
    var mathErrorFeature = context.Features.Get<MathErrorFeature>();
    if (mathErrorFeature is not null)
    {
        if (context.RequestServices.GetService<IProblemDetailsWriter>() is
            { } problemDetailsService)
        {

            if (problemDetailsService.CanWrite(new ProblemDetailsContext() { HttpContext = context }))
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError => ("Divison by zero is not defined.",
                        "https://en.wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                        "https://en.wikipedia.org/wiki/Square_root")
                };

                await problemDetailsService.WriteAsync(new ProblemDetailsContext
                {
                    HttpContext = context,
                    ProblemDetails =
                    {
                        Title = "Bad Input",
                        Detail = details.Detail,
                        Type = details.Type
                    }
                });
            }
        }
    }
});

// /divide?numerator=2&denominator=4
app.MapGet("/divide", (HttpContext context, double numerator, double denominator) =>
{
    if (denominator == 0)
    {
        var errorType = new MathErrorFeature
        {
            MathError = MathErrorType.DivisionByZeroError
        };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(numerator / denominator);
});

// /squareroot?radicand=16
app.MapGet("/squareroot", (HttpContext context, double radicand) =>
{
    if (radicand < 0)
    {
        var errorType = new MathErrorFeature
        {
            MathError = MathErrorType.NegativeRadicandError
        };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

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

app.Run();

Detalles del problema del middleware

Un enfoque alternativo para usar ProblemDetailsOptions con CustomizeProblemDetails es establecer ProblemDetails en middleware. Una respuesta de detalles del problema se puede escribir llamando a IProblemDetailsService.WriteAsync:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStatusCodePages();

// Middleware to handle writing problem details to the response.
app.Use(async (context, next) =>
{
    await next(context);
    var mathErrorFeature = context.Features.Get<MathErrorFeature>();
    if (mathErrorFeature is not null)
    {
        if (context.RequestServices.GetService<IProblemDetailsService>() is
                                                           { } problemDetailsService)
        {
            (string Detail, string Type) details = mathErrorFeature.MathError switch
            {
                MathErrorType.DivisionByZeroError => ("Divison by zero is not defined.",
                "https://en.wikipedia.org/wiki/Division_by_zero"),
                _ => ("Negative or complex numbers are not valid input.", 
                "https://en.wikipedia.org/wiki/Square_root")
            };

            await problemDetailsService.WriteAsync(new ProblemDetailsContext
            {
                HttpContext = context,
                ProblemDetails =
                {
                    Title = "Bad Input",
                    Detail = details.Detail,
                    Type = details.Type
                }
            });
        }
    }
});

// /divide?numerator=2&denominator=4
app.MapGet("/divide", (HttpContext context, double numerator, double denominator) =>
{
    if (denominator == 0)
    {
        var errorType = new MathErrorFeature { MathError =
                                               MathErrorType.DivisionByZeroError };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

    return Results.Ok(numerator / denominator);
});

// /squareroot?radicand=16
app.MapGet("/squareroot", (HttpContext context, double radicand) =>
{
    if (radicand < 0)
    {
        var errorType = new MathErrorFeature { MathError =
                                               MathErrorType.NegativeRadicandError };
        context.Features.Set(errorType);
        return Results.BadRequest();
    }

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

app.MapControllers();

app.Run();

En el código anterior, los puntos de conexión de API mínimas /divide y /squareroot devuelven la respuesta del problema personalizada esperada en la entrada de error.

Los puntos de conexión del controlador de API devuelven la respuesta del problema predeterminada en la entrada de error, no la respuesta del problema personalizada. Se devuelve la respuesta del problema predeterminada porque el controlador de API ha escrito en el flujo de respuesta, Detalles del problema para los códigos de estado de error, antes de llamar a IProblemDetailsService.WriteAsync y la respuesta no se vuelve a escribir.

El siguiente ValuesController devuelve BadRequestResult, que escribe en el flujo de respuesta y, por lo tanto, impide que se devuelva la respuesta del problema personalizado.

[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 Values3Controller devuelve ControllerBase.Problem para que se devuelva el resultado esperado del problema personalizado:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values3Controller : ControllerBase
{
    // /api/values3/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 Problem(
                title: "Bad Input",
                detail: "Divison by zero is not defined.",
                type: "https://en.wikipedia.org/wiki/Division_by_zero",
                statusCode: StatusCodes.Status400BadRequest
                );
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values3/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return Problem(
                title: "Bad Input",
                detail: "Negative or complex numbers are not valid input.",
                type: "https://en.wikipedia.org/wiki/Square_root",
                statusCode: StatusCodes.Status400BadRequest
                );
        }

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

}

Producción de una carga de ProblemDetails para excepciones

Considere la aplicación siguiente:

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

En entornos que no son de desarrollo, cuando se produce una excepción, lo siguiente es una respuesta ProblemDetails estándar que se devuelve al cliente:

{
"type":"https://tools.ietf.org/html/rfc7231#section-6.6.1",
"title":"An error occurred while processing your request.",
"status":500,"traceId":"00-b644<snip>-00"
}

Para la mayoría de las aplicaciones, el código anterior es todo lo que se necesita para las excepciones. Sin embargo, en la sección siguiente se muestra cómo obtener respuestas a problemas más detalladas.

Una alternativa a una página del controlador de excepciones personalizada es proporcionar una expresión lambda en UseExceptionHandler. El uso de una expresión lambda permite acceder al error y escribir una respuesta de detalles del problema con IProblemDetailsService.WriteAsync:

using Microsoft.AspNetCore.Diagnostics;
using static System.Net.Mime.MediaTypeNames;

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();
}
else
{
    app.UseExceptionHandler(exceptionHandlerApp =>
    {
        exceptionHandlerApp.Run(async context =>
        {
            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
            context.Response.ContentType = Text.Plain;

            var title = "Bad Input";
            var detail = "Invalid input";
            var type = "https://errors.example.com/badInput";

            if (context.RequestServices.GetService<IProblemDetailsService>() is
                { } problemDetailsService)
            {
                var exceptionHandlerFeature =
               context.Features.Get<IExceptionHandlerFeature>();

                var exceptionType = exceptionHandlerFeature?.Error;
                if (exceptionType != null &&
                   exceptionType.Message.Contains("infinity"))
                {
                    title = "Argument exception";
                    detail = "Invalid input";
                    type = "https://errors.example.com/argumentException";
                }

                await problemDetailsService.WriteAsync(new ProblemDetailsContext
                {
                    HttpContext = context,
                    ProblemDetails =
                {
                    Title = title,
                    Detail = detail,
                    Type = type
                }
                });
            }
        });
    });
}

app.MapControllers();
app.Run();

Advertencia

No proporciones información de errores confidencial a los clientes. Proporcionar información de los errores es un riesgo para la seguridad.

Un enfoque alternativo para generar detalles del problema es usar el paquete NuGet de terceros Hellang.Middleware.ProblemDetails, que se puede usar para asignar excepciones y errores de cliente a los detalles del problema.

Recursos adicionales

• Vea o descargue el código de ejemplo (cómo descargarlo)
• Solución de problemas de ASP.NET Core en Azure App Service e IIS
• Solución de problemas comunes para Azure App Service e IIS con ASP.NET Core
• Control de errores en las API web basadas en el controlador de ASP.NET Core
• Control de errores en API mínimas.