Add 'extra' details support to WebApi exceptions

Extended all WebApi-related exception constructors to accept an optional 'extra' parameter for additional error context. Updated XML docs accordingly. Added Extra property to WebApiException and included traceId in ProblemDetails. Made AddExtra a public extension method with improved documentation. Minor doc and parameter naming improvements.

Author: Vadim Belov

Sources/EasyExtensions.AspNetCore/Exceptions/AccessDeniedException.cs

@@ -13,8 +13,10 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// access violation.</param>
     /// <param name="message">The error message that explains the reason for the exception. If not specified, a default message of "Access
     /// denied" is used.</param>
-    public class AccessDeniedException(string objectName, string message = "Access denied")
-        : WebApiException(HttpStatusCode.Forbidden, objectName, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class AccessDeniedException(string objectName, string message = "Access denied", object? extra = null)
+        : WebApiException(HttpStatusCode.Forbidden, objectName, message, extra)
     { }
 
     /// <summary>
@@ -23,7 +25,9 @@ public class AccessDeniedException(string objectName, string message = "Access d
     /// </summary>
     /// <typeparam name="T">The type of the resource for which access was denied.</typeparam>
     /// <param name="message">The error message that describes the reason for the access denial.</param>
-    public class AccessDeniedException<T>(string message = "Access denied")
-        : AccessDeniedException(typeof(T).Name, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class AccessDeniedException<T>(string message = "Access denied", object? extra = null)
+        : AccessDeniedException(typeof(T).Name, message, extra)
     { }
 }

Sources/EasyExtensions.AspNetCore/Exceptions/BadRequestException.cs

@@ -11,16 +11,20 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// <param name="objectName">The name of the object or entity associated with the bad request. This value is used to provide context for the
     /// error.</param>
     /// <param name="message">The error message that describes the reason for the bad request. The default is "Bad request".</param>
-    public class BadRequestException(string objectName, string message = "Bad request")
-        : WebApiException(HttpStatusCode.BadRequest, objectName, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class BadRequestException(string objectName, string message = "Bad request", object? extra = null)
+        : WebApiException(HttpStatusCode.BadRequest, objectName, message, extra)
     { }
 
     /// <summary>
     /// Represents an exception that is thrown to indicate a bad request error associated with a specific resource type.
     /// </summary>
     /// <typeparam name="T">The type of the resource or entity related to the bad request.</typeparam>
     /// <param name="message">The error message that describes the reason for the bad request. The default is "Bad request".</param>
-    public class BadRequestException<T>(string message = "Bad request")
-        : BadRequestException(typeof(T).Name, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class BadRequestException<T>(string message = "Bad request", object? extra = null)
+        : BadRequestException(typeof(T).Name, message, extra)
     { }
 }

Sources/EasyExtensions.AspNetCore/Exceptions/DuplicateException.cs

@@ -13,8 +13,10 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// creation attempts in resource management scenarios.</remarks>
     /// <param name="objectName">The name of the object that caused the conflict.</param>
     /// <param name="message">The error message that describes the reason for the conflict. The default is "Object already exists."</param>
-    public class DuplicateException(string objectName, string message = "Object already exists")
-        : WebApiException(HttpStatusCode.Conflict, objectName, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class DuplicateException(string objectName, string message = "Object already exists", object? extra = null)
+        : WebApiException(HttpStatusCode.Conflict, objectName, message, extra)
     { }
 
     /// <summary>
@@ -23,7 +25,9 @@ public class DuplicateException(string objectName, string message = "Object alre
     /// </summary>
     /// <typeparam name="T">The type of the object that caused the duplication error.</typeparam>
     /// <param name="message">The error message that explains the reason for the exception. The default is "Object already exists."</param>
-    public class DuplicateException<T>(string message = "Object already exists")
-        : DuplicateException(typeof(T).Name, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class DuplicateException<T>(string message = "Object already exists", object? extra = null)
+        : DuplicateException(typeof(T).Name, message, extra)
     { }
 }

Sources/EasyExtensions.AspNetCore/Exceptions/EntityInvalidTypeException.cs

@@ -14,7 +14,9 @@ public class EntityInvalidTypeException(string message) : Exception(message)
         /// <summary>
         /// Throws an exception indicating that the entity type is invalid.
         /// </summary>
-        /// <exception cref="EntityInvalidTypeException">Thrown when the entity type is invalid.</exception>
+        /// <exception cref="EntityInvalidTypeException">Thrown when the entity type is invalid.</exception>'
+        /// <param name="value">The value that is being checked for the expected type.</param>
+        /// <param name="paramName">Optional name of the parameter being validated.</param>
         public static TEntity ThrowIfInvalidType<TEntity>(object? value, string? paramName = null)
         {
             if (value is not TEntity typed)

Sources/EasyExtensions.AspNetCore/Exceptions/EntityNotFoundException.cs

@@ -11,16 +11,20 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// <param name="objectName">The name of the entity that was not found. This value is included in the exception details to identify the
     /// missing entity.</param>
     /// <param name="message">The error message that describes the reason for the exception. The default is "Entity was not found".</param>
-    public class EntityNotFoundException(string objectName, string message = "Entity was not found")
-        : WebApiException(HttpStatusCode.NotFound, objectName, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class EntityNotFoundException(string objectName, string message = "Entity was not found", object? extra = null)
+        : WebApiException(HttpStatusCode.NotFound, objectName, message, extra)
     { }
 
     /// <summary>
     /// Represents an exception that is thrown when an entity of the specified type cannot be found.
     /// </summary>
     /// <typeparam name="T">The type of the entity that was not found.</typeparam>
     /// <param name="message">The error message that explains the reason for the exception. If not specified, a default message is used.</param>
-    public class EntityNotFoundException<T>(string message = "Entity was not found")
-        : EntityNotFoundException(typeof(T).Name, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class EntityNotFoundException<T>(string message = "Entity was not found", object? extra = null)
+        : EntityNotFoundException(typeof(T).Name, message, extra)
     { }
 }

Sources/EasyExtensions.AspNetCore/Exceptions/UnauthorizedException.cs

@@ -13,8 +13,10 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// resource.</remarks>
     /// <param name="objectName">The name of the object or resource for which access was denied.</param>
     /// <param name="message">The error message that describes the reason for the unauthorized access. The default is "Unathorized".</param>
-    public class UnauthorizedException(string objectName, string message = "Unathorized")
-        : WebApiException(HttpStatusCode.Unauthorized, objectName, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class UnauthorizedException(string objectName, string message = "Unathorized", object? extra = null)
+        : WebApiException(HttpStatusCode.Unauthorized, objectName, message, extra)
     { }
 
     /// <summary>
@@ -23,7 +25,9 @@ public class UnauthorizedException(string objectName, string message = "Unathori
     /// </summary>
     /// <typeparam name="T">The type of the resource or entity for which authorization failed.</typeparam>
     /// <param name="message">The error message that explains the reason for the exception. The default is "Unathorized".</param>
-    public class UnauthorizedException<T>(string message = "Unathorized")
-        : UnauthorizedException(typeof(T).Name, message)
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class UnauthorizedException<T>(string message = "Unathorized", object? extra = null)
+        : UnauthorizedException(typeof(T).Name, message, extra)
     { }
 }

Sources/EasyExtensions.AspNetCore/Exceptions/WebApiException.cs

@@ -3,6 +3,7 @@
 
 using EasyExtensions.Abstractions;
 using EasyExtensions.Models;
+using Microsoft.AspNetCore.Mvc;
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
@@ -21,7 +22,14 @@ namespace EasyExtensions.AspNetCore.Exceptions
     /// protocol.</param>
     /// <param name="objectName">The name of the object or entity related to the error. Used to identify the source of the error in the response.</param>
     /// <param name="message">The error message that describes the reason for the exception.</param>
-    public class WebApiException(HttpStatusCode statusCode, string objectName, string message) : Exception(message), IHttpError
+    /// <param name="extra">Optional additional error details. This parameter can be used to provide extra information about the error, such as specific permission
+    /// requirements, user roles, or any other relevant context that may help in understanding the access denial.</param>
+    public class WebApiException(
+        HttpStatusCode statusCode,
+        string objectName,
+        string message,
+        object? extra = null)
+            : Exception(message), IHttpError
     {
         /// <summary>
         /// HTTP status code.
@@ -33,12 +41,29 @@ public class WebApiException(HttpStatusCode statusCode, string objectName, strin
         /// </summary>
         public string ObjectName { get; } = objectName;
 
+        /// <summary>
+        /// Additional error details. This property can be used to provide extra 
+        /// information about the error, such as validation errors, stack traces, or any
+        /// </summary>
+        public object? Extra { get; } = extra;
+
         /// <summary>
         /// Get error model.
         /// </summary>
         /// <returns> Error model. </returns>
         public ErrorModel GetErrorModel()
         {
+            ProblemDetails details = new ProblemDetails()
+            {
+                Status = (int)StatusCode,
+                Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1",
+                Title = "Web API actions errors occurred.",
+            };
+            string? traceId = Activity.Current?.Id ?? "-";
+            if (!string.IsNullOrWhiteSpace(traceId))
+            {
+                details.Extensions["traceId"] = traceId;
+            }
             return new()
             {
                 Status = (int)StatusCode,

Sources/EasyExtensions.AspNetCore/Extensions/ControllerBaseExtensions.cs

@@ -195,7 +195,18 @@ private static void AddTraceId(ControllerBase controller, ProblemDetails details
             }
         }
 
-        private static void AddExtra(ProblemDetails details, object? extra)
+        /// <summary>
+        /// Adds additional information to the specified <see cref="ProblemDetails"/> instance by populating its <see
+        /// cref="ProblemDetails.Extensions"/> property with key-value pairs from the provided object.
+        /// </summary>
+        /// <remarks>If <paramref name="extra"/> is a dictionary, its key-value pairs are added directly
+        /// to the <see cref="ProblemDetails.Extensions"/> property. If it is an object, its public properties
+        /// (excluding indexers) are added as key-value pairs. Existing keys in <see cref="ProblemDetails.Extensions"/>
+        /// may be overwritten.</remarks>
+        /// <param name="details">The <see cref="ProblemDetails"/> instance to which extra information will be added. Cannot be null.</param>
+        /// <param name="extra">An object containing additional data to add to the <see cref="ProblemDetails.Extensions"/> property. This
+        /// can be a dictionary with string keys or an object with public properties. If null, no changes are made.</param>
+        public static void AddExtra(this ProblemDetails details, object? extra)
         {
             if (extra is null)
             {