Interface ITransportReceiver
Defines the minimal interface for receiving messages from a transport source.
Replaces the bloated ICloudMessageConsumer (11 methods) with a focused contract (3 methods + GetService).
public interface ITransportReceiver : IAsyncDisposable
- Inherited Members
- Extension Methods
Remarks
Follows the Microsoft.Extensions.AI IChatClient pattern:
- Minimal surface area — only core receive/ack/reject operations.
- Advanced features (visibility timeout, start/stop, streaming) via GetService(Type).
- Cross-cutting concerns (telemetry, DLQ routing) via DelegatingTransportReceiver decorators.
Properties
Source
Gets the source name (queue or subscription) this receiver is configured for.
string Source { get; }
Property Value
- string
The source name.
Methods
AcknowledgeAsync(TransportReceivedMessage, CancellationToken)
Requests acknowledgement of successful processing of a message.
Task AcknowledgeAsync(TransportReceivedMessage message, CancellationToken cancellationToken)
Parameters
messageTransportReceivedMessageThe message to acknowledge.
cancellationTokenCancellationTokenCancellation token for the operation.
Returns
- Task
Task representing the acknowledgment operation.
Remarks
Returning normally means the provider completed the supported acknowledgement operation without reporting failure or refusal through its available response. Confirmation guarantees depend on the transport; completion does not guarantee durable broker acceptance or prevent redelivery. An implementation must throw on an observed failure, refusal, or unsupported operation. Callers must remain idempotent.
Exceptions
- TransportSettlementException
The acknowledgement could not be completed or its outcome could not be determined. The broker may have accepted it before the failure became observable. Read RedeliveryExpectation to see whether the transport could determine redelivery, and Retryability before retrying the settlement. Clients of this interface must be idempotent.
GetService(Type)
Gets the underlying transport service (e.g., IConsumer, ServiceBusReceiver, IAmazonSQS).
object? GetService(Type serviceType)
Parameters
serviceTypeTypeThe type of service to retrieve.
Returns
Remarks
Follows the IChatClient.GetService() pattern from Microsoft.Extensions.AI.
Returns null if the requested service type is not available.
The default implementation answers for any service this instance itself implements, so a transport that provides one directly need not override it. A transport overrides it to hand out its native SDK handle, and a decorator overrides it to answer for itself before deferring to the transport it wraps.
Exceptions
- ArgumentNullException
Thrown when
serviceTypeis null.
ReceiveAsync(int, CancellationToken)
Receives messages from the source.
Task<IReadOnlyList<TransportReceivedMessage>> ReceiveAsync(int maxMessages, CancellationToken cancellationToken)
Parameters
maxMessagesintMaximum number of messages to receive.
cancellationTokenCancellationTokenCancellation token for the operation.
Returns
- Task<IReadOnlyList<TransportReceivedMessage>>
The received messages.
RejectAsync(TransportReceivedMessage, string?, bool, CancellationToken)
Rejects a message and optionally requeues it for retry.
Task RejectAsync(TransportReceivedMessage message, string? reason, bool requeue, CancellationToken cancellationToken)
Parameters
messageTransportReceivedMessageThe message to reject.
reasonstringThe reason for rejection.
requeueboolWhether to requeue the message for retry.
cancellationTokenCancellationTokenCancellation token for the operation.
Returns
- Task
Task representing the reject operation.
Remarks
requeue states the outcome the caller requires: true asks
the broker to deliver the message again, false asks it not to. Not every broker
can suppress redelivery for a single message, and an implementation that cannot deliver the
requested disposition must throw rather than silently substitute another operation. Normal return
means the supported operation completed without an observed failure or refusal; broker confirmation
and subsequent delivery depend on the transport.
Exceptions
- TransportSettlementException
The rejection could not be completed or its outcome could not be determined. The broker may have accepted it before the failure became observable. Read RedeliveryExpectation to see whether the message is expected to arrive again, and Retryability before retrying the settlement. A failed
requeue: falsemay leave a poison message queued.