---
title: SAIF.NetCore.ErrorHandler overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ErrorHandler
reference_type: package
---

# SAIF.NetCore.ErrorHandler overview

> **Documentation context:** Packaged Component (NuGet)

`SAIF.NetCore.ErrorHandler` is an implementation-layer NuGet package that centralizes exception translation and formatting for two hosting models: ASP.NET Core HTTP pipelines, through `ErrorHandler`/`IErrorHandler`, and Windows Service hosts, through `WindowsServiceErrorHandler`/`IWindowsServiceErrorHandler`. It codes only against `SAIF.NetCore.ServiceContracts` interfaces and relies on the host application to supply the logging and environment implementations and to wire it into the pipeline.

## Purpose
- Translate any exception caught by a host's pipeline or task runner into a consistent, loggable, and (for HTTP hosts) client-facing representation, without the host reimplementing exception classification or response formatting.
- Provide two parallel, independently usable entry points: `ErrorHandler.LogAndReturnException` for ASP.NET Core responses, and `WindowsServiceErrorHandler.HandleError` for Windows Service task failures.
- Offer extensibility points — the `BeginErrorHandling`/`ErrorHandled` events and the pluggable `SpecialErrorAction`/`SpecialErrorAction<T>` list — so a Windows Service host can veto logging, inspect or add context, or run custom recovery/notification logic without modifying this library.

## Responsibilities
- Log every handled HTTP exception at Error level, capture the logger's returned ID as the response's `Error-ID` correlation header, and also return a `Server-Name` header identifying the host machine.
- Classify exceptions for HTTP hosts in precedence order — `HttpStatusCodeException`, then `SAIFException`, then any other `Exception` — each producing a different status code, content type, and handled/unhandled body (the legacy `[Obsolete]` `ErrorHandler.Invoke` path; the current `DynamicErrorHandler` in `SAIF.NetCore.ServiceExtensions` re-implements the same precedence).
- Build and log a formatted, multi-line Windows Service error, raising `BeginErrorHandling` and `ErrorHandled` events so a host can veto logging, add context objects, or suppress special actions.
- Execute pluggable, fire-conditional special error actions that return a `SpecialErrorActionResult`; only the wrapped action delegate is caught, so a throwing fire-condition predicate, a non-conforming `ISpecialErrorAction` override, or a throwing failure-logger call can still escape and stop the remaining actions (and the subsequent `ErrorHandled` event) from running.
- Flatten exception stack traces across the inner-exception chain and extract `SAIFException.LogDetails` as strings for inclusion in logged output.

## Key components
- `ErrorHandler` / `IErrorHandler`: the ASP.NET Core-facing exception-to-response translator.
- `WindowsServiceErrorHandler` / `IWindowsServiceErrorHandler` (ServiceContracts): the Windows Service-facing exception handler, owning the `BeginErrorHandling`/`ErrorHandled` events, the `SpecialErrorActions` list, and the `ShutdownExemptExceptionTypes` list.
- `SpecialErrorAction` / `SpecialErrorAction<T>`: delegate wrappers with an optional fire-condition predicate.
- `ContextContainer` (`IErrorContextContainer`): the string-keyed object bag passed to special actions during error handling.
- `WindowsServiceError` (`IWindowsServiceError`/`IStandardErrorLogInfo`): formats the identity, timestamp, exception, and log details into the logged error text.
- `ExceptionExtensions`: static helpers for stack-trace flattening and `SAIFException.LogDetails` extraction.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `src/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/ErrorHandler.cs`
- `src/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/ExceptionExtensions.cs`
- `src/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/SAIF.NetCore.ErrorHandler/WindowsService/WindowsServiceErrorHandler.cs`