DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult 2025.0.6-preview-325

This is a prerelease version of DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult.
There is a newer version of this package available.
See the version list below for details.
dotnet add package DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult --version 2025.0.6-preview-325
                    
NuGet\Install-Package DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult -Version 2025.0.6-preview-325
                    
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="DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult" Version="2025.0.6-preview-325" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult" Version="2025.0.6-preview-325" />
                    
Directory.Packages.props
<PackageReference Include="DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult" />
                    
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 DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult --version 2025.0.6-preview-325
                    
#r "nuget: DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult, 2025.0.6-preview-325"
                    
#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 DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult@2025.0.6-preview-325
                    
#: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=DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult&version=2025.0.6-preview-325&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult&version=2025.0.6-preview-325&prerelease
                    
Install as a Cake Tool

ASP.NET Core WebApp Self-Documented Problem Result Extension

© 2024 DotNet Brightener

NuGet Version

Introduction

Have you ever wanted to have a consistent way of returning errors from your ASP.NET Core Web application? This package provides an abstraction for responding errors from your application to the client, base on the RFC 9457 specification.

When the application encounter an error, it should return a ProblemDetails object that contains information about the error.

This package

  • Added a global exception handler to catch unhandled exceptions and return a ProblemDetails object. An ILogger is also added to log the exception automatically for the unhandled exceptions.

  • Provides a based IProblembResult interface and its extension methods ToProblemDetails() or ToProblemResult(), to create consistent error responses. The error response format is based on the RFC 9457 specification.

When your application needs to response the error, you can either throw an exception derived from BaseProblemDetailsError class or simply create a class that implements IProblemResult interface. The error object will be converted to ProblemDetails object and returned to the client. Check Usage section for more information.

Installation

You can install the package from NuGet:


dotnet add package DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult

Usage

1. Enable the global exception handler

Add the following code to your Startup.cs (if you use Startup.cs) or Program.cs (by default) file:


// this can be omitted if your application already added IHttpContextAccessor
builder.Services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();

// The default way of handling unhandled exceptions
builder.Services.AddExceptionHandler<UnhandledExceptionResponseHandler>();

// Adds services required for creation of <see cref="ProblemDetails"/> for failed requests.
builder.Services.AddProblemDetails();


// Add the following to your Configure method, 
// or after 
// var app = builder.Build(); if you use Program.cs
app.UseExceptionHandler();

After the configuration above, if your application throws an exception, the response will be a ProblemDetails object.

2. Create a consistent error response

2.1. Using Exception approach

Traditionally we used to throw exceptions when there are errors. You can create an exception class that inherits BaseProblemDetailsError class. The <summary> and <remarks> XML comments will be used to generate the ProblemDetails object.


/// <summary>
///     The error represents the requested object of type `User` could not be found
/// </summary>
/// <remarks>
///     The error is thrown because the requested resource of type `User` could not be found
/// </remarks>
public class UserNotFoundException : BaseProblemDetailsError
{
    public UserNotFoundException()
        : base("User Not Found", HttpStatusCode.BadRequest)
    {
    }

    public UserNotFoundException(long userId)
        : this()
    {
        Data.Add("userId", userId);
    }
}

Somewhere in your application, where an error is expected, you can throw the exception as followed:

// UserService.cs

    public User GetUser(long userId)
    {
        var user = _userRepository.GetUser(userId);

        if (user == null)
        {
            throw new UserNotFoundException(userId);
        }

        return user;
    }

Without having to handle the exception, the error will be caught by the global exception handler and return a ProblemDetails object.

// UserController.cs

    [HttpGet("{userId}")]
    public IActionResult GetUserDetail(long userId)
    {
        var user = _userService.GetUser(userId);

        // Without handling the exception, the error will be caught by the global exception handler

        return Ok(user);
    }

2.2. Using ProblemResult approach

Create a class that inherits BaseProblemDetailsError. The <summary> and <remarks> XML comments will be used to generate the ProblemDetails object.


using AspNet.Extensions.SelfDocumentedProblemResult.ErrorResults;

/// <summary>
///     The error represents the requested object of type `User` could not be found
/// </summary>
/// <remarks>
///     The error is thrown because the requested resource of type `User` could not be found
/// </remarks>
public class UserNotFoundError : BaseProblemDetailsError
{
    public UserNotFoundError()
        : base(HttpStatusCode.NotFound)
    {

    }

    public UserNotFoundError(long userId)
        : this()
    {
        Data.Add("userId", userId);
    }
}

// UserService.cs

    public User GetUser(long userId)
    {
        var user = _userRepository.GetUser(userId);

        return user;
    }

Somewhere in your controller, where an error is expected, you can return the error like this:

// UserController.cs
    [HttpGet("{userId}")]
    public IActionResult GetUserDetail(long userId)
    {
        var user = _userService.GetUser(userId);
        if (user == null)
        {
            // Explicitly return the error
            var error = new UserNotFoundError(userId);

            return error.ToProblemResult();
        }

        // Omited for brevity
    }

In the above snippet, where the user is not found, a response of status code 404 will be returned with the following body:


{
   "type": "UserNotFoundError",
   "title": "User Not Found Error",
   "status": 404,
   "detail": "The error is thrown because the requested resource of type `User` could not be found",
   "instance": "/users/123",
   "data": {
       "userId": 123
   }
}

The XML comments for the class will be used to generate the detail information about the error. It can be useful if you use the UI package, as the error information can be obtain via the UI.

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net9.0

    • No dependencies.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult:

Package Downloads
DotNetBrightener.WebApp.CommonShared

Package Description

DotNetBrightener.WebApi.GenericCRUD

Package Description

DotNetBrightener.LocaleManagement

Package Description

DotNetBrightener.AspNet.Extensions.SelfDocumentedProblemResult.UI

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2025.0.9-preview-509 155 10/2/2025
2025.0.9-preview-508 140 10/2/2025
2025.0.9-preview-487 230 9/29/2025
2025.0.9-preview-481 223 9/29/2025
2025.0.9-preview-473 199 9/28/2025
2025.0.8 231 9/23/2025
2025.0.6 228 9/22/2025
2025.0.6-preview-455 237 9/22/2025
2025.0.6-preview-454 321 9/17/2025
2025.0.6-preview-441 171 9/14/2025
2025.0.6-preview-440 169 9/14/2025
2025.0.6-preview-406 203 9/2/2025
2025.0.6-preview-401 182 9/2/2025
2025.0.6-preview-400 194 9/2/2025
2025.0.6-preview-369 224 8/27/2025
2025.0.6-preview-368 226 8/27/2025
2025.0.6-preview-334 220 8/18/2025
2025.0.6-preview-333 140 7/27/2025
2025.0.6-preview-332 508 7/24/2025
2025.0.6-preview-331 513 7/24/2025
2025.0.6-preview-328 516 7/24/2025
2025.0.6-preview-327 386 7/21/2025
2025.0.6-preview-326 393 7/21/2025
2025.0.6-preview-325 300 7/20/2025
2025.0.6-preview-324 297 7/20/2025
2025.0.6-preview-322 299 7/20/2025
2025.0.6-preview-321 302 7/19/2025
2025.0.6-preview-320 301 7/19/2025
2025.0.6-preview-319 209 7/17/2025
2025.0.6-preview-317 205 7/17/2025
2025.0.6-preview-316 208 7/17/2025
2025.0.6-preview-315 205 7/17/2025
2025.0.6-preview-314 207 7/17/2025
2025.0.6-preview-313 210 7/17/2025
2025.0.6-preview-312 202 7/16/2025
2025.0.5 219 7/10/2025
2025.0.5-preview-307 137 7/5/2025
2025.0.4 137 7/5/2025
2025.0.4-preview-305 176 7/4/2025
2025.0.4-preview-304 215 7/1/2025
2025.0.4-preview-299 183 5/31/2025
2025.0.4-preview-298 165 5/30/2025
2025.0.4-preview-296 191 5/30/2025
2025.0.4-preview-295 204 5/29/2025
2025.0.4-preview-293 218 5/26/2025
2025.0.4-preview-292 220 5/26/2025
2025.0.3 200 2/10/2025
2025.0.3-preview-288 182 2/10/2025
2025.0.2 179 1/21/2025
2025.0.2-preview-278 171 1/21/2025
2025.0.2-preview-277 186 12/16/2024
2025.0.1-rc-243301701 462 11/25/2024
2024.0.14.6 209 11/25/2024
2024.0.14.6-rc-243031001 269 10/29/2024
2024.0.14.6-rc-243030701 207 10/29/2024
2024.0.14.6-rc-242840501 197 10/10/2024
2024.0.14.6-rc-242820305 187 10/8/2024
2024.0.14.6-rc-242771401 339 10/3/2024
2024.0.14.6-rc-242770501 182 10/3/2024
2024.0.14.6-rc-242770201 209 10/3/2024
2024.0.14.6-rc-242761801 187 10/2/2024
2024.0.14.6-rc-242761601 216 10/2/2024
2024.0.14.6-rc-242761501 183 10/2/2024
2024.0.14.6-rc-242761401 209 10/2/2024
2024.0.14.6-rc-242760701 209 10/2/2024
2024.0.14.6-rc-242751002 191 10/1/2024
2024.0.14.6-rc-242750901 233 10/1/2024
2024.0.14.6-rc-242750502 184 10/1/2024
2024.0.14.6-rc-242750201 198 10/1/2024
2024.0.14.6-rc-242741501 190 9/30/2024
2024.0.14.6-rc-242730701 207 9/29/2024
2024.0.14.6-preview-2730501 174 9/29/2024
2024.0.14.6-preview-2701501 240 9/26/2024
2024.0.14.6-preview-2620901 251 9/18/2024
2024.0.14.6-preview-2570701 196 9/13/2024
2024.0.14.6-preview-2510703 274 9/7/2024
2024.0.14.6-preview-2480501 223 9/4/2024
2024.0.14.6-preview-2430401 242 8/30/2024
2024.0.14.6-preview-242730701 198 9/29/2024
2024.0.14.6-preview-2421703 205 8/29/2024
2024.0.14.6-preview-2421701 190 8/29/2024
2024.0.14.6-preview-2420901 201 8/29/2024
2024.0.14.6-preview-2390101 230 8/26/2024
2024.0.14.6-preview-2381603 226 8/25/2024
2024.0.14.6-preview-2341601 233 8/21/2024
2024.0.14.6-preview-2321602 211 8/20/2024
2024.0.14.6-preview-2190801 241 8/6/2024
2024.0.14.6-preview-2041501 174 7/22/2024
2024.0.14.6-preview-1920603 282 7/10/2024
2024.0.14.6-preview-1920301 198 7/10/2024
2024.0.14.6-preview-1911302 212 7/9/2024
2024.0.14.6-preview-1901001 204 7/8/2024
2024.0.14.6-preview-1900901 199 7/8/2024
2024.0.14.6-preview-1900801 188 7/8/2024
2024.0.14.6-preview-1860304 177 7/4/2024
2024.0.14.5 241 7/1/2024
2024.0.14.5-preview-1811601 200 6/29/2024
2024.0.14.5-preview-1810501 214 6/29/2024
2024.0.14.5-preview-180132 207 6/28/2024
2024.0.14.5-preview-180131 179 6/28/2024
2024.0.14.5-preview-180121 179 6/28/2024
2024.0.14.4 221 6/27/2024
2024.0.14.4-preview-8 151 6/27/2024
2024.0.14.4-preview-7 194 6/27/2024
2024.0.14.4-preview-6 133 6/27/2024
2024.0.14.3 199 6/21/2024
2024.0.14.1 207 6/6/2024
2024.0.14.1-preview 176 6/6/2024
2024.0.14-preview-1 176 6/6/2024
2024.0.13.8-preview 186 6/6/2024
2024.0.13.2-preview-247 140 6/6/2024
2024.0.13.1-preview-0146 183 6/6/2024
2024.0.13-preview-1 155 6/6/2024
2024.0.12.15803-preview-03 177 6/6/2024
2024.0.12.15608 203 6/4/2024
2024.0.12.15515 267 6/3/2024
2024.0.12.15220 202 5/31/2024
2024.0.12.15220-alpha31-240... 175 5/31/2024
2024.0.12.14911 242 5/28/2024
2024.0.12.14910-alpha28-240... 176 5/28/2024
2024.0.12.14823 218 5/27/2024
2024.0.12.14522-alpha7-2405... 186 5/24/2024
2024.0.12.14514-alpha6-2405... 182 5/24/2024
2024.0.12.14511 227 5/24/2024
2024.0.12.14314 260 5/22/2024
2024.0.12.14114 240 5/20/2024
2024.0.12.12815 260 5/7/2024
2024.0.12.12814 201 5/7/2024
2024.0.12.12721 220 5/6/2024
2024.0.12.12702 219 5/5/2024
2024.0.12.12622 235 5/5/2024
2024.0.12.12514 223 5/4/2024
2024.0.12.12512 250 5/4/2024
2024.0.12.12510 236 5/4/2024
2024.0.12.12420 174 5/3/2024
2024.0.12.12319 181 5/2/2024
2024.0.12.12319-rc-2405021801 158 5/2/2024
2024.0.12.12318 172 5/2/2024
2024.0.12.12215 217 5/1/2024
2024.0.12.12011 225 4/29/2024
2024.0.12.11720 222 4/26/2024
2024.0.12.11719 225 4/26/2024
2024.0.12.11621 239 4/25/2024
2024.0.12.11523 215 4/24/2024
2024.0.12.11522 236 4/24/2024
2024.0.12.11417 218 4/23/2024
2024.0.12.11400 227 4/22/2024
2024.0.12.11316 240 4/22/2024
2024.0.11.10220 230 4/11/2024
2024.0.11.10120 202 4/10/2024
2024.0.11.10119 181 4/10/2024
2024.0.11.10115 193 4/10/2024
2024.0.11.9914 241 4/8/2024
2024.0.11.9901 202 4/7/2024
2024.0.11.9823 224 4/7/2024
2024.0.11.9401 235 4/2/2024
2024.0.11.9301 213 4/1/2024
2024.0.11.9206 237 3/31/2024
2024.0.11.9205 232 3/31/2024