TailoredApps.Shared.ExceptionHandling¶
Opis¶
Biblioteka standaryzuje obsługę wyjątków w aplikacjach ASP.NET Core Web API. Rozwiązuje problem niespójnych odpowiedzi błędów — zamiast nieobrobionych stack traces lub przypadkowych formatów JSON każdy błąd jest konwertowany na ujednoliconą strukturę ExceptionHandlingResultModel (errorCode, message, errors[]).
Dostarcza dwa mechanizmy:
- Middleware (
ConfigureExceptionHandler) — globalny handler przechwytujący nieobsłużone wyjątki dla całej aplikacji - Action Filter (
HandleExceptionAttribute+AddExceptionHandlingFilterAttribute) — zwraca tę samą strukturę dla nieprawidłowegoModelStatena poziomie kontrolera/akcji
Wbudowany DefaultExceptionHandlingProvider mapuje ValidationException (FluentValidation) na 400 z błędami per pole, a każdy inny wyjątek na 500 z ogólnym komunikatem. Możesz zaimplementować własny IExceptionHandlingProvider, który mapuje wyjątki domenowe na inne kody HTTP.
Instalacja¶
Rejestracja w DI¶
// Program.cs
using TailoredApps.Shared.ExceptionHandling.Interfaces;
using TailoredApps.Shared.ExceptionHandling.Providers;
using TailoredApps.Shared.ExceptionHandling.WebApiCore;
using TailoredApps.Shared.ExceptionHandling.WebApiCore.Middleware;
// Wbudowany provider (400 dla walidacji, 500 + ogólny komunikat dla reszty)
builder.Services
.AddExceptionHandlingForWebApi<IExceptionHandlingProvider, DefaultExceptionHandlingProvider>();
// ...lub własny provider:
// .AddExceptionHandlingForWebApi<IExceptionHandlingProvider, MyExceptionHandlingProvider>();
// Opcja A: globalny filter MVC (nieprawidłowy ModelState -> ustrukturyzowane 400)
builder.Services.AddControllers(options =>
{
options.Filters.AddExceptionHandlingFilterAttribute();
});
// Opcja B: middleware (preferowane dla globalnej obsługi nieobsłużonych wyjątków)
var app = builder.Build();
app.ConfigureExceptionHandler();
Przykład użycia¶
Własny provider mapujący wyjątki domenowe¶
using FluentValidation;
using Microsoft.AspNetCore.Mvc.ModelBinding;
using TailoredApps.Shared.ExceptionHandling.Interfaces;
using TailoredApps.Shared.ExceptionHandling.Model;
public class MyExceptionHandlingProvider : IExceptionHandlingProvider
{
private readonly bool includeDetails;
public MyExceptionHandlingProvider(IHostEnvironment env) => includeDetails = env.IsDevelopment();
public ExceptionHandlingResultModel Response(Exception exception)
{
var root = exception.GetBaseException();
return root switch
{
ValidationException ve => new ExceptionHandlingResultModel(400, ve.Message,
ve.Errors.Select(e => new ExceptionOrValidationError(e.PropertyName, e.ErrorMessage))),
NotFoundException nf => new ExceptionHandlingResultModel(404, nf.Message,
new[] { new ExceptionOrValidationError("", nf.Message) }),
UnauthorizedAccessException => new ExceptionHandlingResultModel(401, "Unauthorized",
new[] { new ExceptionOrValidationError("", "Unauthorized") }),
// Nigdy nie zwracaj root.Message poza Development: może zawierać connection string, ścieżki lub SQL.
_ => new ExceptionHandlingResultModel(500,
includeDetails ? root.Message : "An unexpected error occurred.",
new[] { new ExceptionOrValidationError("", includeDetails ? root.Message : "An unexpected error occurred.") }),
};
}
public ExceptionHandlingResultModel Response(ModelStateDictionary modelState)
=> new ExceptionHandlingResultModel(modelState); // 400 "Validation Failed" + błędy pól
}
Wynikowy format JSON odpowiedzi błędu¶
{
"message": "Validation Failed",
"errorCode": 400,
"errors": [
{ "field": "Email", "message": "Email address is required" },
{ "message": "Name must not be empty" }
]
}
Właściwość field jest pomijana (serializacja WhenWritingNull), gdy błąd nie dotyczy konkretnego pola.
🔒 Bezpieczeństwo¶
- Szczegóły wyjątków nie wyciekają domyślnie.
DefaultExceptionHandlingProviderzwraca500z komunikatem"An unexpected error occurred."dla wszystkiego, co nie jest błędem walidacji. Komunikat pierwotnego wyjątku jest dołączany tylko wtedy, gdy provider został utworzony zIHostEnvironmentw środowisku Development, lub jawnie przeznew DefaultExceptionHandlingProvider(includeExceptionDetails: true). Wcześniej komunikat najgłębszego wyjątku (błędy SQL, nazwy hostów, ścieżki plików) trafiał do każdego anonimowego klienta jako HTTP 400. - Poprawne kody statusu. Awarie serwera to 5xx, więc alerty, load balancery i polityki retry klientów widzą je jako awarie. Middleware ogranicza
ErrorCodeprovidera do zakresu 400–599, aExceptionOccuredResulthonoruje kod z modelu zamiast wymuszać 400. - Głośny błąd konfiguracji. Middleware rozwiązuje
IExceptionHandlingServiceprzezGetRequiredService, więc pominięcieAddExceptionHandlingForWebApidaje czytelny wyjątek zamiast pustego 500. - Błąd klienta nie jest błędem serwera (3.0). Wyjątek, któremu provider nadał status 4xx (walidacja, brak zasobu), nie trafia do logu jako
An unhandled exception has occurred…na poziomie Error i nie dodaje taguerror.typedo metrykihttp.server.request.duration— alerty na błędy serwera nie reagują na złe dane od klienta. Wyjątek jest zapisywany na poziomie Debug w kategoriiTailoredApps.Shared.ExceptionHandling. Odpowiedzi 5xx są logowane jako błędy, jak dotąd; 404 wybrane przez providera jest wysyłane jako 404.
API Reference¶
| Typ | Rodzaj | Opis |
|---|---|---|
ExceptionHandlingResultModel |
Klasa | Wynikowy obiekt: ErrorCode (HTTP), Message, Errors (lista); konstruktory (int code, string message, IEnumerable<ExceptionOrValidationError>), (string message, IEnumerable<...>) = 400, (ModelStateDictionary) = 400 |
ExceptionOrValidationError |
Klasa | Model błędu: Field (nullable) + Message |
IExceptionHandlingProvider |
Interfejs | Mapuje Exception i ModelStateDictionary na ExceptionHandlingResultModel |
DefaultExceptionHandlingProvider |
Klasa | Wbudowany provider: walidacja → 400, reszta → 500 z ogólnym komunikatem; szczegóły tylko w Development |
IExceptionHandlingService |
Interfejs | Wyższy poziom — wywołuje provider i zwraca response |
ExceptionHandlingConfiguration.AddExceptionHandlingForWebApi |
Metoda ext. | Rejestruje serwis + provider w DI |
ExceptionHandlingConfiguration.AddExceptionHandlingFilterAttribute |
Metoda ext. | Dodaje filtr ModelState do MVC |
ExceptionMiddlewareExtensions.ConfigureExceptionHandler |
Metoda ext. | Dodaje middleware do pipeline |
HandleExceptionAttribute |
Atrybut | Oznacza akcje/kontrolery, których nieprawidłowy ModelState konwertuje filtr |
ExceptionOccuredResult |
ObjectResult | Wynik HTTP z modelem; status z ErrorCode |
🤖 AI Agent Prompt¶
## TailoredApps.Shared.ExceptionHandling — Instrukcja dla agenta AI
Używasz biblioteki TailoredApps.Shared.ExceptionHandling do standaryzacji błędów API.
### Rejestracja
```csharp
builder.Services.AddExceptionHandlingForWebApi<IExceptionHandlingProvider, DefaultExceptionHandlingProvider>();
// Opcja A - middleware (globalnie):
app.ConfigureExceptionHandler();
// Opcja B - filter MVC (nieprawidłowy ModelState):
builder.Services.AddControllers(o => o.Filters.AddExceptionHandlingFilterAttribute());
```
### Co zostaje skonfigurowane
- IExceptionHandlingService + provider (transient), middleware zapisujący JSON z ErrorCode providera
- DefaultExceptionHandlingProvider: ValidationException -> 400 z błędami pól; wszystko inne -> 500 "An unexpected error occurred."
### Własny provider (rzeczywiste API)
```csharp
public class MyProvider : IExceptionHandlingProvider
{
public ExceptionHandlingResultModel Response(Exception ex) => ex.GetBaseException() switch
{
NotFoundException nf => new ExceptionHandlingResultModel(404, nf.Message, [new ExceptionOrValidationError("", nf.Message)]),
ValidationException ve => new ExceptionHandlingResultModel(400, ve.Message,
ve.Errors.Select(e => new ExceptionOrValidationError(e.PropertyName, e.ErrorMessage))),
_ => new ExceptionHandlingResultModel(500, "An unexpected error occurred.", [new ExceptionOrValidationError("", "An unexpected error occurred.")])
};
public ExceptionHandlingResultModel Response(ModelStateDictionary ms) => new(ms);
}
```
### Format odpowiedzi
```json
{ "message": "Validation Failed", "errorCode": 400, "errors": [{ "field": "Email", "message": "Required" }, { "message": "Global error" }] }
```
### Zasady
- Nigdy nie zwracaj exception.Message dla nieoczekiwanych błędów poza Development — użyj ogólnego komunikatu i statusu 500
- ErrorCode musi być z zakresu 400–599; middleware mapuje inne wartości na 500
- ExceptionOrValidationError z pustym field (string.Empty) → pole Field = null w JSON (pomijane)
- Provider musi implementować OBA przeciążenia: Response(Exception) i Response(ModelStateDictionary)
- ConfigureExceptionHandler obsługuje WSZYSTKIE nieobsłużone wyjątki — filter konwertuje tylko nieprawidłowy ModelState
- Wyjątki, które są błędem klienta, mapuj w providerze na 4xx (nie trafiają wtedy do logu jako Error); błędy serwera zostawiaj jako 5xx
- [HandleException] działa na poziomie akcji ORAZ klasy kontrolera
- Dla zagnieżdżonych wyjątków użyj GetBaseException(), by znaleźć pierwotną przyczynę
- Używaj AddExceptionHandlingFilterAttribute; błędnie zapisane AddExceptionHAndlingFilterAttribute usunięto w 3.0