TailoredApps.Shared.ExceptionHandling 3.0.0-preview.1

This is a prerelease version of TailoredApps.Shared.ExceptionHandling.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package TailoredApps.Shared.ExceptionHandling --version 3.0.0-preview.1
                    
NuGet\Install-Package TailoredApps.Shared.ExceptionHandling -Version 3.0.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TailoredApps.Shared.ExceptionHandling" Version="3.0.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="TailoredApps.Shared.ExceptionHandling" Version="3.0.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="TailoredApps.Shared.ExceptionHandling" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add TailoredApps.Shared.ExceptionHandling --version 3.0.0-preview.1
                    
#r "nuget: TailoredApps.Shared.ExceptionHandling, 3.0.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package TailoredApps.Shared.ExceptionHandling@3.0.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=TailoredApps.Shared.ExceptionHandling&version=3.0.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=TailoredApps.Shared.ExceptionHandling&version=3.0.0-preview.1&prerelease
                    
Install as a Cake Tool

TailoredApps.Shared.ExceptionHandling

One error format for an ASP.NET Core Web API. Unhandled exceptions and invalid model state are turned into the same response model, ExceptionHandlingResultModel (message, errorCode, errors), by an IExceptionHandlingProvider that decides the status code and the text for each exception.

Installation

dotnet add package TailoredApps.Shared.ExceptionHandling

Registration

using TailoredApps.Shared.ExceptionHandling.Interfaces;
using TailoredApps.Shared.ExceptionHandling.Providers;
using TailoredApps.Shared.ExceptionHandling.WebApiCore;
using TailoredApps.Shared.ExceptionHandling.WebApiCore.Middleware;

builder.Services.AddExceptionHandlingForWebApi<IExceptionHandlingProvider, DefaultExceptionHandlingProvider>();
builder.Services.AddControllers(options => options.Filters.AddExceptionHandlingFilterAttribute());

var app = builder.Build();
app.ConfigureExceptionHandler();   // unhandled exceptions -> JSON error response

DefaultExceptionHandlingProvider answers a FluentValidation ValidationException with 400 and one error per failed property, and every other exception with 500 and the text An unexpected error occurred.

Usage

A provider of your own maps domain exceptions to other status codes:

using Microsoft.AspNetCore.Mvc.ModelBinding;
using TailoredApps.Shared.ExceptionHandling.Interfaces;
using TailoredApps.Shared.ExceptionHandling.Model;
using TailoredApps.Shared.ExceptionHandling.Providers;

public class ApiExceptionHandlingProvider : IExceptionHandlingProvider
{
    private readonly DefaultExceptionHandlingProvider defaults = new();

    public ExceptionHandlingResultModel Response(Exception exception)
        => exception.GetBaseException() is KeyNotFoundException
            ? new ExceptionHandlingResultModel(404, "Not found.", new[] { new ExceptionOrValidationError("", "Not found.") })
            : defaults.Response(exception);

    public ExceptionHandlingResultModel Response(ModelStateDictionary modelState) => defaults.Response(modelState);
}

// Program.cs
builder.Services.AddExceptionHandlingForWebApi<IExceptionHandlingProvider, ApiExceptionHandlingProvider>();

The response written by the middleware:

{
  "message": "Not found.",
  "errorCode": 404,
  "errors": [
    { "message": "Not found." }
  ]
}

An error tied to a field also carries "field"; the property is left out when the field name is empty.

Good to know

  • DefaultExceptionHandlingProvider returns the real exception message only when it is created with an IHostEnvironment that is in Development, or with includeExceptionDetails: true. Its parameterless constructor never does. Do the same in your own provider: exception messages can contain connection strings, paths and SQL.
  • The middleware (ConfigureExceptionHandler) is what handles exceptions. The filter only replaces the result of an action with invalid model state, and only on actions or controllers marked with [HandleException].
  • The HTTP status is the model's ErrorCode. The middleware answers 500 and the filter result 400 when the code is outside 400-599. If the response has already started, the middleware writes nothing.
  • An exception the provider answers with 4xx (validation, a missing resource) is the client's mistake: the middleware logs no "unhandled exception" error for it and adds no error.type tag to the request metric; it is logged at Debug in the TailoredApps.Shared.ExceptionHandling category. A 5xx answer is logged as an error, as before. A 404 the provider chose is sent as such.
  • ExceptionHandlingResultModel(message, errors) and ExceptionHandlingResultModel(modelState) use code 400; the latter has the message Validation Failed and one error per model-state entry.
  • The middleware needs AddExceptionHandlingForWebApi: it resolves IExceptionHandlingService and throws when the service is not registered. AddExceptionHAndlingFilterAttribute is the obsolete, misspelled name of AddExceptionHandlingFilterAttribute.

Documentation

https://shared.tailoredapps.pl/en/Libraries/ExceptionHandling/

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0-preview.2 50 11/12/2026
3.0.0-preview.1 51 11/12/2026
2.1.0 101 11/12/2026
2.0.1 100 11/12/2026
2.0.0 109 11/12/2026
1.6.0 94 11/12/2026
1.4.19 459 10/26/2026
1.4.18 571 10/23/2026
1.4.17 953 10/6/2026
1.4.16 115 9/28/2026
1.4.15 114 9/21/2026
1.4.14 120 8/20/2026
1.4.13 126 8/20/2026
1.4.12 132 8/20/2026
1.4.11 133 8/7/2026
1.4.10 245 7/8/2026
1.4.9 143 7/8/2026
1.4.8 153 7/6/2026
1.4.7 154 5/20/2026
1.4.6 140 5/20/2026
Loading failed