Table of Contents

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

statusCode int

The HTTP status code associated with the exception.

errorCode string

The error code associated with this exception.

message string

The error message that explains the reason for the exception.

innerException Exception

The 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

message string

The 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

message string

The error message that explains the reason for the exception.

innerException Exception

The 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

errorCode string

The error code associated with this exception.

message string

The 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

errorCode string

The error code associated with this exception.

message string

The error message that explains the reason for the exception.

innerException Exception

The 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

string

The current ErrorCode 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

string

The current SpanId 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

string

The current TraceId 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 name
  • Title: The exception type name in human-readable form
  • ErrorCode: From GetProblemDetailsErrorCode() (defaults to status code)
  • Status: The HTTP status code
  • Detail: The exception message
  • Instance: A unique URN using the exception's Id
  • Extensions: 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

key string

The context key.

value object

The context value.

Returns

DispatchException

The current exception instance for fluent configuration.

WithCorrelationId(string)

Sets the correlation ID for the exception.

public DispatchException WithCorrelationId(string correlationId)

Parameters

correlationId string

The 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

statusCode int

The 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

suggestedAction string

The 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

userMessage string

The user-friendly message.

Returns

DispatchException

The current exception instance for fluent configuration.