EMH.Lib.Patterns.ExceptionProcessor.Logging 3.2.24

EMH.Lib.Patterns.ExceptionProcessor

Consistent exception handling for .NET — behind an interface your projects can depend on without pulling in a logger.

Why

Class libraries need to handle exceptions, but they shouldn't dictate how the application logs them.

This package splits the two apart. Your libraries reference .Interface only — a tiny contract with no logging dependency. The host application decides which implementation to register at startup. Swap the implementation and nothing downstream changes.

┌──────────────────┐    references     ┌───────────────────────┐
│  Your libraries  │ ────────────────▶ │  .Interface           │
└──────────────────┘   contract only   │  IExceptionProcessor  │
                                       └───────────────────────┘
                                                   ▲
┌──────────────────┐                               │ implements
│  Host / startup  │ ─── picks one ──▶  .Logging · .Console · custom
└──────────────────┘

Packages

dotnet add package EMH.Lib.Patterns.ExceptionProcessor.Interface   # in your libraries
dotnet add package EMH.Lib.Patterns.ExceptionProcessor.Logging     # in your host

Quick start

Logging implementation

HippoLog must be initialised once, before the processor is used.

HippoLog.Initialize(myAdapter);   // e.g. SerilogAdapterFactory.Create()

IExceptionProcessor processor = LoggingExceptionProcessorFactory.Create();

Console implementation

IExceptionProcessor processor = ConsoleExceptionProcessorFactory.Create();

Registering with a container

container.RegisterSingleton(() => processor);

Usage

Wrap a call and let the policy decide whether the exception propagates:

// Default policy is LogAndThrowPolicy — logs, then rethrows.
this.processor.Process(() => VoidFunction());

int x = this.processor.Process(() => NonVoidFunction(param));

// Log, swallow, and carry on.
this.processor.Process(() => NonCriticalFunction(), ExceptionProcessorPolicies.LogAndResumePolicy);

// Supply a fallback instead of default(T).
string name = this.processor.Process(
    () => LookupName(id),
    "unknown",
    ExceptionProcessorPolicies.LogAndResumePolicy);

Async equivalents mirror the synchronous ones:

var result = await this.processor.ProcessAsync(() => FetchAsync(id));
await this.processor.ProcessAsync(() => SendAsync(), ExceptionProcessorPolicies.LogAndResumePolicy);

Already inside a catch? Ask the processor what to do, or just log:

try
{
    Function();
}
catch (Exception e)
{
    if (this.processor.HandleException(e, ExceptionProcessorPolicies.LogAndThrowPolicy))
    {
        throw;
    }
}

try
{
    Function();
}
catch (Exception e)
{
    this.processor.LogException(e);   // logs only, never rethrows
}

Policies

ExceptionProcessorPolicies decides whether the exception is rethrown after logging.

Only LogAndResumePolicy suppresses the rethrow — anything else fails safe, so an unset policy never silently swallows an exception. When resuming, Process<TResponse> returns default(TResponse) unless you passed an explicit fallback.

Custom handling

Override the rule by supplying your own IHandlingStrategy:

public sealed class AlwaysResumeStrategy : IHandlingStrategy
{
    public bool ShouldThrow(ExceptionProcessorPolicies policy) => false;
}

IExceptionProcessor processor = LoggingExceptionProcessorFactory.Create(new AlwaysResumeStrategy());

Calling Create() with no argument returns a shared default processor. Passing a strategy returns a separate instance using it — the shared default is left untouched.

Cancellation

The logging implementation deliberately does not log an OperationCanceledException whose cancellation token was already cancelled — a caller cancelling its own work is expected, not an error. The throw decision is still applied as normal. Cancellations from other causes (a timeout, say) are logged like any other exception.

Building

The solution lives in src/.

cd src
dotnet build -c Release      # zero warnings enforced; StyleCop violations fail the build
dotnet test -c Release
dotnet test -c Release --collect:"XPlat Code Coverage" --results-directory ./TestResults

Components target netstandard2.0; the test project targets net10.0 and requires the .NET 10 SDK. All dependencies resolve from nuget.org, so no private feed is needed to build — CI configures one only in order to publish.

Versioning

v3.1 made LoggingExceptionProcessorFactory.Create honour a supplied IHandlingStrategy. Before this the processor was cached on the first call and any strategy passed later was discarded, so the result depended on call order. Code passing a custom strategy will now see it applied where it was previously ignored.

v3 replaced ILogger with HippoLog. Earlier releases took an ILogger at construction; HippoLog.Initialize is now called once by the host instead.

Both implementation packages share a version number. The patch component is the CI build number, so it is not contiguous between releases.

License

MIT © Email Hippo Ltd