01
Qué es y qué problema resuelve
Una excepción expresa un fallo que interrumpe el recorrido normal. Un manejador central evita repetir try/catch y filtrar diagnósticos en cada endpoint.
No conviertas todos los errores de negocio en excepciones si ya pueden representarse como un resultado esperado.
02
Ejemplo paso a paso
Punto de partida Configuración básica; no incluye un handler propio. Define políticas de errores conocidos y registros en tu integración.
Antes de ejecutar
Requiere un host ASP.NET Core 10 preparado. builder y app corresponden a WebApplication.CreateBuilder y Build; las variables y tipos auxiliares deben definirse. Registra los servicios usados antes de Build. El ZIP de consola no contiene esta API.
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
// Los endpoints posteriores quedan dentro del manejo configurado.Cómo funciona
- Registra el soporte de ProblemDetails y el manejador de excepciones.
- Coloca el manejo global donde pueda observar los fallos posteriores.
- Distingue un rechazo esperado de una excepción y de una cancelación solicitada.
Resultado esperado: Un fallo inesperado posterior puede traducirse a una respuesta controlada sin traza pública.
03
Cuándo usarlo y qué debes evitar
Configura servicios y middleware, y separa cancelación solicitada de error interno. En .NET 10, un IExceptionHandler que atiende una excepción puede suprimir ciertos diagnósticos por defecto; revisa la política para conservar observabilidad sin duplicados.
La página de desarrollo pertenece al entorno de desarrollo controlado.
Ampliación opcional · contexto y variantes del tema
ProblemDetails y errores con significado
Una respuesta de error consistente incluye tipo, título, estado y un identificador de correlación. El detalle debe ayudar al consumidor sin revelar SQL, nombres internos, rutas locales ni credenciales. Para fallos inesperados devuelve un mensaje genérico y conserva el diagnóstico en un registro protegido. Para conflictos esperados ofrece un código estable que el cliente pueda interpretar sin analizar una frase.
AddProblemDetails registra servicios; UseExceptionHandler intercepta fallos del pipeline. No confundas configurarlos con capturar toda excepción dentro de cada caso de uso. Una cancelación solicitada por el cliente no es automáticamente un 500. En .NET 10, un IExceptionHandler que devuelve true suprime por defecto ciertos diagnósticos de excepciones atendidas: revisa SuppressDiagnosticsCallback o registra explícitamente lo que necesitas sin duplicarlo.
Punto de partida Coloca el manejo de errores antes de componentes susceptibles de fallar. Este fragmento no añade un IExceptionHandler propio: usa la respuesta ProblemDetails predeterminada y agrega correlación.
Antes de ejecutar
Configuración ASP.NET Core 10
builder.Services.AddProblemDetails(opciones =>
{
opciones.CustomizeProblemDetails = contexto =>
contexto.ProblemDetails.Extensions["traceId"] =
contexto.HttpContext.TraceIdentifier;
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();Resultado esperado: Errores compatibles pueden incluir traceId; la respuesta no expone la excepción original.
04 · Práctica guiada · opcional
Practica lo aprendido
Provoca un fallo de prueba y una cancelación del cliente; registra diferencias.
- 01Prepara el ejemplo con las dependencias indicadas en «Antes de ejecutar».
- 02Provoca un fallo de prueba y una cancelación del cliente; registra diferencias.
- 03Comprueba y registra el resultado: Un fallo inesperado posterior puede traducirse a una respuesta controlada sin traza pública.
Ver solución orientativa
El fallo inesperado requiere diagnóstico protegido; la cancelación sigue su política y no se etiqueta automáticamente como 500.
05
Comprueba lo aprendido
Responde antes de abrir la explicación. Esta comprobación es opcional y no guarda una puntuación.
01¿Atrapar Exception y devolver éxito mejora disponibilidad?
No. Oculta fallos y comunica un resultado falso.
02¿Por qué una cancelación del cliente requiere una decisión diferente a un fallo inesperado?
La cancelación puede ser una interrupción esperada, mientras el fallo requiere diagnóstico de una operación que no pudo completarse. Aplica políticas distintas y evita afirmar éxito en ambos casos.
Cómo demostrar el objetivo
Compara tu práctica con estos resultados. Si solo diseñaste una prueba, registra su resultado como esperado, no como observado.
- El fallo inesperado posterior al manejador produce una respuesta controlada, sin traza pública.
- La cancelación tiene una política distinta y nunca se traduce automáticamente a éxito.
Qué debes recordar
- Los fallos inesperados necesitan diagnóstico interno.
- Los rechazos de negocio y la cancelación requieren semánticas propias.
Tu cuaderno · notas personales
Cuaderno local
Tus notas del contenido
Se guardan únicamente en este dispositivo. Puedes exportarlas cuando quieras.
Material de apoyo · descarga, glosario y referencias
Explicaciones, ejemplos y prácticas propios de Academia de Software. Los fragmentos de integración requieren las dependencias indicadas; el ZIP contiene el núcleo de consola. Las lecturas externas se consultan en su sitio original y conservan sus condiciones. Procedencia y condiciones de uso.