Class TransportSettlementException
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
messagestringThe 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
messagestringThe message that describes the error.
innerExceptionExceptionThe 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
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
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
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.