Skip to content

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.

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