UtilKit.ExceptionHandler 1.0.0

UtilKit.ExceptionHandler

A global exception handling middleware for .NET APIs. Catches unhandled exceptions, logs them, and returns a clean JSON error response. Never leaks stack traces or internal details to clients.

Install

dotnet add package UtilKit.ExceptionHandler

Quick Start

// Program.cs
app.UseUtilKitExceptionHandler();

That's it. Any unhandled exception now returns:

HTTP 500:

{
  "message": "An unexpected error occurred"
}

No stack trace. No internal details. Safe for production.

Configuration

Custom error message

app.UseUtilKitExceptionHandler(options =>
{
    options.DefaultMessage = "Something went wrong. Please try again.";
    options.DefaultStatusCode = 500;
});

Development mode (show exception details)

if (app.Environment.IsDevelopment())
{
    app.UseUtilKitExceptionHandler(options =>
    {
        options.DefaultMessage = "An error occurred";
        options.IncludeExceptionType = true;
        options.IncludeStackTrace = true;
    });
}
else
{
    app.UseUtilKitExceptionHandler();
}

Development response:

{
  "message": "An error occurred",
  "type": "NullReferenceException",
  "stackTrace": "at MyApp.Services..."
}

Production response:

{
  "message": "An error occurred"
}

With ExceptionHandlerOptions object

app.UseUtilKitExceptionHandler(new ExceptionHandlerOptions
{
    DefaultMessage = "Server error",
    DefaultStatusCode = 500,
    IncludeExceptionType = false,
    IncludeStackTrace = false
});

Options

⚠️ Never enable IncludeStackTrace in production. Stack traces expose internal code structure and are a security risk.

What it does

1. Wraps your entire request pipeline in a try-catch
2. If any exception is thrown and not handled:
   • Logs the full exception (with stack trace) via ILogger
   • Returns a clean JSON response to the client
   • Never exposes internal details in production

Exception Mapping

Use built-in defaults (one line)

app.UseUtilKitExceptionHandler(options =>
{
    options.UseDefaultMappings();
});

Default mappings:

Custom mapping

app.UseUtilKitExceptionHandler(options =>
{
    options.UseDefaultMappings();
    options.Map<MyCustomException>(418, "I'm a teapot");
    options.Map<PaymentException>(402); // uses exception message
});

Throw in your code

// Returns 404 with message
throw new NotFoundException("User with ID 123 not found");

// Returns 409 with message
throw new ConflictException("Email already registered");

// Returns 500 with fixed message (hides DB details)
throw new DatabaseException("Connection timeout", sqlException);

Placement

Add it first in the middleware pipeline — before everything else:

var app = builder.Build();

app.UseUtilKitExceptionHandler(); // First!
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

Disclaimer

This package is provided "as is" without warranty of any kind. The author(s) are not responsible for any damages, data loss, security breaches, or issues arising from the use of this package. It is the consumer's responsibility to:

• Test thoroughly in their environment before production use
• Review exception messages to ensure no sensitive data is exposed
• Never enable IncludeStackTrace in production
• Implement additional security measures as needed for their application

Use at your own risk.

License

MIT