The Siemens.AspNet.ErrorHandling package provides middleware and services for handling errors in ASP.NET Core
applications. It includes features for translating error messages based on the "Accepted Languages" header, making it
easier to build multilingual applications with standardized error responses. The package is designed to work seamlessly
with its companion package,
Siemens.AspNet.ErrorHandling.ContractsLink to Documentation,
which defines the core error handling models and base classes like ProblemDetails and ValidationProblemDetails.
By using RFC 7807, we ensure that error responses are consistent,
easily interpretable by clients, and capable of conveying rich, structured information about errors. This approach
enhances interoperability and helps developers diagnose issues more effectively.
🚀 Installation
You can install the package using NuGet:
.NET CLI
dotnet add package Siemens.AspNet.ErrorHandling
NuGet Package Manager Console
Install-Package Siemens.AspNet.ErrorHandling
📌 Getting Started
1. Register the Middleware and Services
In your ASP.NET Core application, you need to register the error handling services in the Startup.cs or Program.cs file.
AddErrorHandling adds all services for handling response error and logging (see the example below).
If you want to add only the error logging, please add and use AddErrorLogHandling and UseErrorLogHandling.
If you want to add only the handler itself to handle the error responses, please add AddErrorResponseHandling and
UseErrorResponseHandling.
When using the AddErrorHandling method, it will also add the following service options:
if you override the default behavior of the RouteHandlerOptions make sure to set the ThrowOnBadRequest=true!
Dotnet 7
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
// Register the error handler services for logging or response handling
// services.AddErrorResponseHandling();
// services.AddErrorLogHandling();
// Register the error handling services
services.AddErrorHandling();
// Other service registrations...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
// Add the error response handling
// app.UseErrorResponseHandling();
// Add the error Logging
// app.UseErrorLogHandling();
// Add the error handling middleware to the request pipeline
app.UseErrorHandlingMiddleware();
// Other middleware...
}
}
Dotnet 8 or higher
var builder = WebApplication.CreateBuilder(args);
// Register the error handler services for logging or response handling
// builder.Services.AddErrorResponseHandling();
// builder.Services.AddErrorLogHandling();
// Register the error handling services
builder.Services.AddErrorHandling();
// Other service registrations...
var app = builder.Build();
app.UseRouting();
// Important to use the full potential setup the error handler after app.UseRouting();
app.UseErrorHandling();
// Other middleware...
app.Run();
With Siemens.AspNet.MinimalApi.Sdk
If you use the Siemens.AspNet.MinimalApi.Sdk (coming soon) package everything is already setup. Just use the
ServerlessMinimalWebApi and everything
is ready to go.
using Pulse.FieldingTool.Api;
using Siemens.AspNet.MinimalApi.Sdk;
var webApi = new ServerlessMinimalWebApi();
webApi.RegisterServices = (service,
config) =>
{
// Domain service registrations
service.AddApi(config);
};
webApi.MapEndpoints = endpoints =>
{
// Map api domain endpoints
endpoints.MapApi();
};
webApi.Run(args);
// This is important that you are able to use
// API test via WebApplicationFactory<Program>
// https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-8.0
namespace Pulse.FieldingTool
{
public partial class Program;
}
⚙️ Optional Configuration
📝 Show Error Details
(Optional)
A new feature has been introduced that allows you to control which error response will be processed and which will ne
hidden from the user
Configuration
To conifgure this feature, add the following configuration to your appsettings.json or set it as an environment
variable:
Default settings:
if you are not configure this settings explicitly everything in the range from 0-499 will be handled and shown. All
above will be hidden.
Sample: Handled response
{
"type": "ValidationProblemDetails",
"title": "Your patch request contains invalid data",
"status": 422,
"detail": "Your PatchFormsConfigurationRequest for the object id: 6f9e1c3e-8fbc-4d2a-9a3d-3c2e8f0b7d2f was invalid. Please check the error details. You might pass invalid data, or try to patch properties which not exists or not allow to patch",
"errors": {
"formsId": [
"FormsId must be either GUID or long.",
"FormsId must not be one or more whitespace. Only GUID or a long is valid for the ProjectId"
]
}
Setup AllowedBodyMetaInfo at your endpoint
You have to pass the type for your http content type (body). Only needed on http endpoints
which have a body like POST, PUT, PATCH.
endpoints.WithMetadata(new AllowedBodyMetaInfo(typeof(CreateFormsConfigurationRequest))); // Your request body type
Use ValidationProblemDetailsExtended``instead of ValidationProblemDetails`
{
"type": "ValidationProblemDetailsExtended",
"title": "Your patch request contains invalid data",
"status": 422,
"detail": "Your PatchFormsConfigurationRequest for the object id: 6f9e1c3e-8fbc-4d2a-9a3d-3c2e8f0b7d2f was invalid. Please check the error details. You might pass invalid data, or try to patch properties which not exists or not allow to patch",
"errors": {
"formsId": [
"FormsId must be either GUID or long.",
"FormsId must not be one or more whitespace. Only GUID or a long is valid for the ProjectId"
]
},
"errorDetails": {
"formsId": {
"currentValue": " ",
"errors": [
"FormsId must be either GUID or long.",
"FormsId must not be one or more whitespace. Only GUID or a long is valid for the ProjectId"
],
"samples": [
"a1b2c3d4-e5f6-7890-1234-567890abcdef",
"1"
],
"location": null
}
},
"Id": "6f9e1c3e-8fbc-4d2a-9a3d-3c2e8f0b7d2f",
"RequestType": "PatchFormsConfigurationRequest",
"RequestContent": {
"formsId": " ",
"projectId": "c36b49ba-bf79-4c86-9d41-8c356634316e",
"title": "$UniqueFormsConfigurationName$",
"formsType": "InvitationOnly",
"startDate": "2025-03-15T18:32:18Z",
"endDate": "2025-04-14T18:23:44Z",
"sessionEndsIn": "00:30:00",
"hasUpdate": false,
"languages": [
{
"englishName": "English (United States)",
"nativeName": "English (United States)",
"tag": "en-US",
"tagThreeLetter": "eng",
"parentTag": "en"
}
],
"properties": {
"exampleKey": "ExampleValue"
}
}
}
Invalid Json:
To have even better json error responses if the json payload is invalid we added a new feature to handle this.
Hint: SampleValues
If you have properties which presents for example an string but can be a Guid or number you can optimize the errors
thrown by System.Text.Json or Newtonsoft.Json easily by adding an attribute over your properties in your request.
This is very useful if you have any crash by your serializers before you enter your endpoint code
public sealed record UpdateFormsConfigurationRequest
{
[SampleValue("a1b2c3d4-e5f6-7890-1234-567890abcdef", "1")]
public required string FormsId { get; init; } // SDC --> FormsId GUID // Pulse --> SurveyInstanceId long
[SampleValue("a1b2c3d4-e5f6-7890-1234-567890abcdef", "1")]
public required string ProjectId { get; init; } // SDC --> GUID // Pulse -->
}
Special Case: ValidationProblemDetailsException
When the thrown exception is a ValidationProblemDetails exception, this configuration not only hides the details but
also filters the validation errors themselves. This ensures that no validation error messages are exposed in the
response.
With this configuration, whenever an error with the specified code (e.g., 400, 422, 500) or within the specified range (
500-590) is thrown, detailed error messages will be hidden from the response.
🌐 Translations
(Optional)
The Siemens.AspNet.ErrorHandling package offers robust support for translating error messages based on the client's "
Accepted Languages" header. This is achieved through a pattern-based approach to localization keys, allowing for
consistent and easily maintainable translations across your application.
Language Handling
The Siemens.AspNet.ErrorHandling package automatically selects the appropriate language for error messages based on
the client's "Accepted-Languages" HTTP header. Here’s how the language handling works:
<b>Language Selection:</b> The package reads the "Accepted-Languages" header from the client's request to determine
the preferred language. This header can contain one or more language codes, and the package will attempt to match
these codes with your available translation files.
<b>Default Language:</b> If the client's preferred language is not available or not specified, the package defaults to
English (en).
<b>Fallback Mechanism:</b> The package leverages the CultureInfo class to handle language fallbacks. If a specific
language variant (e.g., de-DE for German in Germany) is not available, the package will automatically fall back to the
parent language (e.g., de for general German). This ensures that even if a specific translation is missing, the client
still receives an error message in a related language.
For example, if the client requests de-DE (German for Germany) but only de.json is available, the package will use the
translations from de.json. This fallback mechanism ensures that users receive the most appropriate localized content
available.
Translation Files
To manage translations effectively, the Siemens.AspNet.ErrorHandling package uses JSON files for storing localized
error messages. Follow these guidelines to set up your translation files:
<b>File Format</b>: The translation files are in JSON format, where each file corresponds to a specific language.
<b>Folder Organization</b>: Place your translation files in a dedicated folder like "Translations" or "
ErrorTranslations". This helps you easily locate and manage your translation files.
<b>File Naming Convention</b>: Name your translation files based on the language code, such as de.json for German or
en.json for English. This ensures clarity and consistency in your localization resources.
By organizing your translation files in this manner, you can maintain a clean and efficient structure that makes it easy
to manage and update your localized content.
Translation Key Pattern
The translation keys for error messages follow a specific pattern, making it straightforward to manage translations for
different exception types and scenarios. The pattern is as follows:
Title Translation Key: {Caller}.{ExceptionName}.Title.{TheExceptionTitle}
{Caller} - refers to the class or method that raised the exception.
{ExceptionName} - is the name of the exception class.
{TheExceptionTitle} - is a key representing the specific error context.
{ErrorKey} - represents the specific validation or error message key.
Example
Consider a scenario where you have a ValidationDetailsException in a class or method named MyAwesomeClass. The
translation keys might look like this:
{
"MyAwesomeClass.ValidationDetailsException.Title.AUTH_TITLE_KEY": "This is my translated title",
"MyAwesomeClass.ValidationDetailsException.Details.AUTH_TITLE_KEY": "This is my translated details",
"MyAwesomeClass.ValidationDetailsException.Errors.AUTH_TITLE_KEY.Name.Name is required.": "This is my translated errors for name 1",
"MyAwesomeClass.ValidationDetailsException.Errors.AUTH_TITLE_KEY.Name.Name must be at least 3 characters long.": "This is my translated errors for name 2",
"MyAwesomeClass.ValidationDetailsException.Errors.AUTH_TITLE_KEY.Email.Email is not in a valid format.": "This is my translated errors for email"
}
This example shows how to throw an error in your c# code.
var errors = new Dictionary<string, string[]>
{
{ "Name", new[] { "Name is required.", "Name must be at least 3 characters long." } },
{ "Email", new[] { "Email is not in a valid format." } }
};
throw new ValidationDetailsException("AUTH_TITLE_KEY", "AUTH_DETAILS_KEY", errors);
🛠️ Custom Handlers & Logging
🔧 Custom Error Handler
If you have the need to handle specific exceptions in a better way as the current handler supports you can implement
your own specific error handler quite easy:
Implement your specific error handler:
You only have to provide a ProblemDetails object back. You have 3 levels of ProblemDetails:
ProblemDetails
ValidationProblemDetails
ValidationProblemDetailsExtended (best possible output for validations)
internal static class AddExceptionILikeToHandleHandlerExtension
{
public static void AddExceptionILikeToHandleHandler(this IServiceCollection services)
{
services.AddSingletonIfNotExists<ISpecificErrorHandler, ExceptionILikeToHandleHandler>();
}
}
internal sealed class ExceptionILikeToHandleHandler() : SpecificErrorHandler<ExceptionILikeToHandle>
{
protected override Task<ProblemDetails> HandleExceptionAsync(HttpContext context,
ExceptionILikeToHandle exception)
{
// Add here your custom logic, code to extract infos specific on your exception you like to handle in a specific way
var reducedProblemDetails = new ProblemDetails
{
Title = exception.Message,
Status = problemDetails.Status ?? StatusCodes.Status500InternalServerError,
Type = nameof(ProblemDetails),
Detail = exception.Message,
};
return Task.FromResult(exception.ProblemDetails);
}
}
Register your new service
using Pulse.FieldingTool.Api;
using Siemens.AspNet.MinimalApi.Sdk;
var webApi = new ServerlessMinimalWebApi();
webApi.RegisterServices = (service,
config) =>
{
// Domain service registrations
service.AddApi(config);
// Custom error handling
service.AddExceptionILikeToHandleHandler()
};
webApi.MapEndpoints = endpoints =>
{
// Map api domain endpoints
endpoints.MapApi();
};
webApi.Run(args);
📑 Custom Error Logging
If you have the need to handle specific exceptions in a better way as the current handler supports you can implement
your own specific error log handler quite easy:
Implement your specific error log handler:
You only have to provide a ErrorLogInfo object back.
internal static class AddValidationProblemDetailsExtendedExceptionLogHandlerExtensions
{
public static void AddValidationProblemDetailsExtendedExceptionLogHandler(this IServiceCollection services)
{
services.AddExceptionLocalizerService();
services.AddTranslationService();
services.AddExceptionHelper();
services.AddSingletonIfNotExists<ISpecificErrorLogHandler, ValidationProblemDetailsExtendedExceptionLogHandler>();
}
}
internal sealed class ValidationProblemDetailsExtendedExceptionLogHandler(ILogger<DefaultExceptionLogHandler> logger,
JsonSerializerOptions jsonSerializerOptions,
ExceptionHelper exceptionHelper) : SpecificErrorLogHandler<ValidationProblemDetailsExtendedException>(logger, jsonSerializerOptions, exceptionHelper)
{
protected override Task<ErrorLogInfo> GetErrorLogFromAsync(HttpContext httpContext,
ValidationProblemDetailsExtendedException exception)
{
// Here you can implement what ever you like to log or customize it.
var errorLogInfo = new ErrorLogInfo
{
StatusCode = exception.ValidationProblemDetailsExtended.Status ?? 500,
Title = exception.ValidationProblemDetailsExtended.Title ?? "No title provided",
Message = exception.ValidationProblemDetailsExtended.Detail ?? "No details provided",
StackTrace = exception.StackTrace?.Split(Environment.NewLine).ToImmutableList() ?? ImmutableList<string>.Empty,
RequestInfos = httpContext.Request.GetQueryRequestInfo(exception.ValidationProblemDetailsExtended.Extensions).ToImmutableDictionary(k => k.key, v => v.value),
ErrorDetails = exception.ValidationProblemDetailsExtended.ErrorDetails.ToImmutableDictionary(k => k.Key, v => (object?)v.Value),
Extensions = exception.ValidationProblemDetailsExtended.Extensions.AsReadOnly(),
ErrorType = exception.GetType().Name
};
return Task.FromResult(errorLogInfo);
}
}
Register your new service
using Pulse.FieldingTool.Api;
using Siemens.AspNet.MinimalApi.Sdk;
var webApi = new ServerlessMinimalWebApi();
webApi.RegisterServices = (service,
config) =>
{
// Domain service registrations
service.AddApi(config);
// Custom error handling
service.AddValidationProblemDetailsExtendedExceptionLogHandler()
};
webApi.MapEndpoints = endpoints =>
{
// Map api domain endpoints
endpoints.MapApi();
};
webApi.Run(args);