Table of Contents

Class TransportSettlementException

Namespace
Excalibur.Dispatch.Transport
Assembly
Excalibur.Dispatch.Transport.Abstractions.dll

Exception thrown when message settlement failed or its outcome could not be determined.

public sealed class TransportSettlementException : InvalidOperationException, ISerializable
Inheritance
TransportSettlementException
Implements
Inherited Members
Extension Methods

Remarks

Settlement is the acknowledgement or rejection that tells the broker what became of a received message. A failure does not establish the broker's state: the request may have been accepted before a connection failure or timeout became observable. Use RedeliveryExpectation and Retryability to determine the caller's next action.

This exception exists so that failure is not reported as success. A settle call that swallowed its error returned normally, telling the caller the message was settled without establishing that outcome, and any redelivery that followed appeared to the consumer as an unexplained duplicate.

It derives from InvalidOperationException, which is the type the transport receivers already throw from this position, so existing catch (InvalidOperationException) handlers keep working. Catch this type instead to distinguish a settlement failure from an unrelated invalid operation — handler code frequently sits in the same try block, and the base type cannot tell the two apart.

Implementations are required to keep provider-specific exceptions off this boundary: a broker client's own exception type travels as InnerException, so a consumer writing portable code does not have to reference a specific broker's package to catch a settlement failure.

Known gap. Not every shipped transport has been verified against this boundary. Unconverted receivers may expose native exceptions; catching InvalidOperationException alone does not catch arbitrary broker-client failures. Catch this type where conversion is implemented and treat other settlement failures as an unknown outcome. Handle caller-owned cancellation separately according to the transport's cancellation behavior; an internal timeout does not by itself establish caller cancellation or whether the broker accepted settlement.

Constructors

TransportSettlementException()

Initializes a new instance of the TransportSettlementException class.

public TransportSettlementException()

TransportSettlementException(string)

Initializes a new instance of the TransportSettlementException class with a specified error message.

public TransportSettlementException(string message)

Parameters

message string

The message that describes the error.

TransportSettlementException(string, Exception)

Initializes a new instance of the TransportSettlementException class with a specified error message and a reference to the inner exception.

public TransportSettlementException(string message, Exception innerException)

Parameters

message string

The message that describes the error.

innerException Exception

The exception that is the cause of the current exception.

Properties

RedeliveryExpectation

Gets whether the broker is expected to redeliver the message after this failure.

public required TransportRedeliveryExpectation RedeliveryExpectation { get; init; }

Property Value

TransportRedeliveryExpectation

Remarks

This is the discriminator that makes the exception actionable. "The settle failed" on its own does not tell a caller what to do; whether the message is coming back does. See TransportRedeliveryExpectation for what each value obliges the caller to do.

It is required so that a transport must state it. Were it optional, a transport that genuinely could not tell and a transport whose author did not fill it in would produce identical exceptions, and a caller could not distinguish a measured Unspecified from an omission.

Two of the three values are actionable and the third aliases one of them: treat Unspecified exactly as Expected, because assuming the work may arrive again is the safe direction. A switch over this type needs two branches, not three.

Retryability

Gets whether retrying the settlement itself could succeed.

public required SettlementRetryability Retryability { get; init; }

Property Value

SettlementRetryability

Remarks

Separate from RedeliveryExpectation, which says what becomes of the message. This says what becomes of the call. A caller implementing the obvious policy — the settlement failed, so try it again — loops forever against a failure that can never succeed, so the transport has to say which kind it was.

It is required for the same reason as RedeliveryExpectation: a transport that cannot tell must say Unspecified deliberately rather than inherit it by omission.

TransportName

Gets the transport where the settlement failed, such as IbmMq or Mqtt.

public string? TransportName { get; init; }

Property Value

string

Remarks

This identifies the transport family, not the name a connection was registered under in dependency injection. A host wiring more than one transport uses it to tell which one failed.