Class DispatchException
- Namespace
- Excalibur.Dispatch.Exceptions
- Assembly
- Excalibur.Dispatch.dll
Base exception class for all Excalibur framework exceptions. Provides consistent error handling, categorization, and structured error data.
public class DispatchException : ApiException, ISerializable
- Inheritance
-
DispatchException
- Implements
- Derived
- Inherited Members
- Extension Methods
Remarks
This exception extends ApiException to provide a unified exception hierarchy for the Excalibur framework. It adds rich error categorization, distributed tracing support, and fluent configuration capabilities.
The inheritance chain is: Exception → ApiException → DispatchException → [Specialized Exceptions]
Constructors
DispatchException()
Initializes a new instance of the DispatchException class with a default error message.
public DispatchException()
DispatchException(int, string, string, Exception?)
Initializes a new instance of the DispatchException class with a status code, error code, message, and inner exception.
public DispatchException(int statusCode, string errorCode, string message, Exception? innerException)
Parameters
statusCodeintThe HTTP status code associated with the exception.
errorCodestringThe error code associated with this exception.
messagestringThe error message that explains the reason for the exception.
innerExceptionExceptionThe exception that is the cause of the current exception.
DispatchException(string)
Initializes a new instance of the DispatchException class with a specified error message.
public DispatchException(string message)
Parameters
messagestringThe error message that explains the reason for the exception.
DispatchException(string, Exception?)
Initializes a new instance of the DispatchException class with a specified error message and a reference to the inner exception that is the cause of this exception.
public DispatchException(string message, Exception? innerException)
Parameters
messagestringThe error message that explains the reason for the exception.
innerExceptionExceptionThe exception that is the cause of the current exception.
DispatchException(string, string)
Initializes a new instance of the DispatchException class with a specified error code and message.
public DispatchException(string errorCode, string message)
Parameters
errorCodestringThe error code associated with this exception.
messagestringThe error message that explains the reason for the exception.
DispatchException(string, string, Exception?)
Initializes a new instance of the DispatchException class with all properties.
public DispatchException(string errorCode, string message, Exception? innerException)
Parameters
errorCodestringThe error code associated with this exception.
messagestringThe error message that explains the reason for the exception.
innerExceptionExceptionThe exception that is the cause of the current exception.
Properties
Category
Gets the category of the error.
public ErrorCategory Category { get; }
Property Value
- ErrorCategory
The current Category value.
Context
Gets additional contextual data related to the exception.
public Dictionary<string, object?> Context { get; }
Property Value
- Dictionary<string, object>
The current Context value.
CorrelationId
Gets or sets the correlation ID for tracing the error across services.
public string? CorrelationId { get; set; }
Property Value
- string
The current CorrelationId value.
DispatchStatusCode
Gets or sets the HTTP status code override for this exception.
public int? DispatchStatusCode { get; set; }
Property Value
- int?
The HTTP status code when explicitly set, otherwise null. If null, the status code is determined automatically from the Category.
Remarks
This property allows overriding the status code that would be determined by Excalibur.Dispatch.Exceptions.DispatchException.DetermineStatusCode(). When set, it takes precedence over the category-based status code.
Use StatusCode to get the inherited base status code.
ErrorCode
Gets the unique error code associated with this exception.
public string ErrorCode { get; }
Property Value
InstanceId
Gets the unique instance identifier for this specific error occurrence.
public Guid InstanceId { get; }
Property Value
- Guid
The current InstanceId value.
Severity
Gets the severity level of the error.
public ErrorSeverity Severity { get; }
Property Value
- ErrorSeverity
The current Severity value.
SpanId
Gets the span ID from the current activity context, if available.
public string? SpanId { get; }
Property Value
SuggestedAction
Gets or sets suggested actions to resolve the error.
public string? SuggestedAction { get; set; }
Property Value
- string
The current SuggestedAction value.
Timestamp
Gets the timestamp when the exception occurred.
public DateTimeOffset Timestamp { get; }
Property Value
- DateTimeOffset
The current Timestamp value.
TraceId
Gets the trace ID from the current activity context, if available.
public string? TraceId { get; }
Property Value
UserMessage
Gets or sets the user-friendly message that can be displayed to end users.
public string? UserMessage { get; set; }
Property Value
- string
The current UserMessage value.
Methods
ToDispatchProblemDetails()
Converts the exception to a problem details representation.
public virtual DispatchProblemDetails ToDispatchProblemDetails()
Returns
- DispatchProblemDetails
A problem details object representing this exception.
ToProblemDetails()
Converts this exception to RFC 7807 problem details format.
public override MessageProblemDetails ToProblemDetails()
Returns
- MessageProblemDetails
A MessageProblemDetails instance representing this exception.
Remarks
This method creates a standardized problem details response suitable for API error responses. The generated problem details follows RFC 7807 and includes:
Type: A URN derived from the exception type nameTitle: The exception type name in human-readable formErrorCode: From GetProblemDetailsErrorCode() (defaults to status code)Status: The HTTP status codeDetail: The exception messageInstance: A unique URN using the exception's IdExtensions: From GetProblemDetailsExtensions() (derived types can add custom data)
Derived classes can override GetProblemDetailsErrorCode() and GetProblemDetailsExtensions() to customize the problem details without overriding the entire method.
WithContext(string, object?)
Adds contextual information to the exception.
public DispatchException WithContext(string key, object? value)
Parameters
Returns
- DispatchException
The current exception instance for fluent configuration.
WithCorrelationId(string)
Sets the correlation ID for the exception.
public DispatchException WithCorrelationId(string correlationId)
Parameters
correlationIdstringThe correlation ID.
Returns
- DispatchException
The current exception instance for fluent configuration.
WithStatusCode(int)
Sets the HTTP status code override for the exception.
public DispatchException WithStatusCode(int statusCode)
Parameters
statusCodeintThe HTTP status code.
Returns
- DispatchException
The current exception instance for fluent configuration.
WithSuggestedAction(string)
Sets a suggested action to resolve the error.
public DispatchException WithSuggestedAction(string suggestedAction)
Parameters
suggestedActionstringThe suggested action.
Returns
- DispatchException
The current exception instance for fluent configuration.
WithUserMessage(string)
Sets a user-friendly message for the exception.
public DispatchException WithUserMessage(string userMessage)
Parameters
userMessagestringThe user-friendly message.
Returns
- DispatchException
The current exception instance for fluent configuration.