Interface IAwsSqsTransportBuilder
Fluent builder interface for configuring AWS SQS transport.
public interface IAwsSqsTransportBuilder
- Extension Methods
Examples
services.AddAwsSqsTransport("orders", sqs =>
{
sqs.UseRegion("us-east-1")
.ConfigureQueue(queue => queue.VisibilityTimeout(TimeSpan.FromMinutes(5)))
.ConfigureFifo(fifo => fifo.ContentBasedDeduplication(true))
.MapQueue<OrderCreated>("https://sqs.us-east-1.amazonaws.com/123/orders");
});
Remarks
This interface follows the Microsoft-style fluent builder pattern. It provides the single entry point for AWS SQS transport configuration.
All methods return this for method chaining, enabling a fluent configuration experience.
Methods
ConfigureCloudEvents(Action<AwsSqsCloudEventOptions>)
Configures CloudEvents settings for the AWS SQS transport.
IAwsSqsTransportBuilder ConfigureCloudEvents(Action<AwsSqsCloudEventOptions> configure)
Parameters
configureAction<AwsSqsCloudEventOptions>The action to configure CloudEvents options.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.ConfigureCloudEvents(ce =>
{
ce.UseFifoFeatures = true;
ce.DefaultMessageGroupId = "orders";
ce.EnableContentBasedDeduplication = true;
ce.EnablePayloadCompression = true;
ce.CompressionThreshold = 64 * 1024;
});
Remarks
Use this method to configure CloudEvents-specific settings such as:
- FIFO features (message group ID, deduplication)
- Payload compression for large events
- DoD compliance validation
- Delayed message delivery
Exceptions
- ArgumentNullException
Thrown when
configureis null.
ConfigureFifo(Action<IAwsSqsFifoBuilder>)
Configures the FIFO queue settings using a fluent builder.
IAwsSqsTransportBuilder ConfigureFifo(Action<IAwsSqsFifoBuilder> configure)
Parameters
configureAction<IAwsSqsFifoBuilder>The FIFO configuration action.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.ConfigureFifo(fifo =>
{
fifo.ContentBasedDeduplication(true)
.MessageGroupIdSelector<OrderCreated>(msg => msg.TenantId);
});
Remarks
FIFO queues provide exactly-once processing and strict ordering. When using FIFO queues, remember that:
- Queue names must end with
.fifosuffix - A message group ID selector is required
- Either content-based deduplication or a deduplication ID selector is required
Exceptions
- ArgumentNullException
Thrown when
configureis null.
ConfigureProvisioning(Action<AwsSqsProvisioningOptions>)
Configures optional, opt-in startup provisioning of dead-letter redrive policies and SNS subscriptions.
IAwsSqsTransportBuilder ConfigureProvisioning(Action<AwsSqsProvisioningOptions> configure)
Parameters
configureAction<AwsSqsProvisioningOptions>The provisioning configuration action.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Remarks
Provisioning is disabled by default; a messaging framework must not mutate cloud infrastructure unless the operator explicitly opts in.
Exceptions
- ArgumentNullException
Thrown when
configureis null.
ConfigureQueue(Action<IAwsSqsQueueBuilder>)
Configures the standard SQS queue settings using a fluent builder.
IAwsSqsTransportBuilder ConfigureQueue(Action<IAwsSqsQueueBuilder> configure)
Parameters
configureAction<IAwsSqsQueueBuilder>The queue configuration action.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.ConfigureQueue(queue =>
{
queue.VisibilityTimeout(TimeSpan.FromMinutes(5))
.MessageRetentionPeriod(TimeSpan.FromDays(7))
.ReceiveWaitTimeSeconds(20)
.DeadLetterQueue(dlq =>
{
dlq.QueueArn("arn:aws:sqs:us-east-1:123456789012:orders-dlq")
.MaxReceiveCount(3);
});
});
Remarks
Use this method to configure queue-level settings such as visibility timeout, message retention period, and dead-letter queue configuration.
Exceptions
- ArgumentNullException
Thrown when
configureis null.
ConfigureSns(Action<IAwsSqsSnsBuilder>)
Configures SNS topic integration using a fluent builder.
IAwsSqsTransportBuilder ConfigureSns(Action<IAwsSqsSnsBuilder> configure)
Parameters
configureAction<IAwsSqsSnsBuilder>The SNS configuration action.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.ConfigureSns(sns =>
{
sns.TopicPrefix("myapp-")
.AutoCreateTopics(true)
.RawMessageDelivery(true)
.MapTopic<OrderCreated>("arn:aws:sns:us-east-1:123:orders")
.SubscribeQueue<OrderCreated>(sub =>
{
sub.TopicArn("arn:aws:sns:us-east-1:123:orders")
.QueueUrl("https://sqs.us-east-1.amazonaws.com/123/orders")
.FilterPolicy(filter =>
{
filter.Attribute("priority").Equals("high");
});
});
});
Remarks
SNS integration enables pub/sub messaging patterns where messages published to SNS topics are delivered to subscribed SQS queues with optional filter policies.
Filter policies allow selective message delivery based on message attributes, reducing unnecessary message processing.
Exceptions
- ArgumentNullException
Thrown when
configureis null.
ConfigureVisibilityHeartbeat(Action<AwsSqsVisibilityHeartbeatOptions>)
Configures the in-flight visibility-timeout heartbeat for the wired subscriber.
IAwsSqsTransportBuilder ConfigureVisibilityHeartbeat(Action<AwsSqsVisibilityHeartbeatOptions> configure)
Parameters
configureAction<AwsSqsVisibilityHeartbeatOptions>The heartbeat configuration action.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Remarks
The heartbeat extends a message's visibility while a long-running handler executes, preventing redelivery before the handler completes. It is opt-in.
Exceptions
- ArgumentNullException
Thrown when
configureis null.
MapQueue<TMessage>(string)
Maps a message type to a specific queue URL.
IAwsSqsTransportBuilder MapQueue<TMessage>(string queueUrl) where TMessage : class
Parameters
queueUrlstringThe SQS queue URL for this message type.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Type Parameters
TMessageThe message type to map.
Examples
sqs.MapQueue<OrderCreated>("https://sqs.us-east-1.amazonaws.com/123456789012/orders")
.MapQueue<PaymentReceived>("https://sqs.us-east-1.amazonaws.com/123456789012/payments");
Remarks
When a mapping exists for a message type, the transport will send that message to the specified queue URL instead of using the default queue.
Exceptions
- ArgumentException
Thrown when
queueUrlis null, empty, or whitespace.
UseMaxPayloadBytes(int?)
Sets the maximum inbound-payload length, in bytes, enforced at both SQS ingress surfaces (receiver and subscriber) before the body is materialized/deserialized.
IAwsSqsTransportBuilder UseMaxPayloadBytes(int? maxPayloadBytes)
Parameters
maxPayloadBytesint?The maximum inbound-payload length in bytes (positive), or null to opt out (unbounded). Defaults to the SQS provider ceiling of 256 KiB.
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Remarks
An over-limit message is rejected at ingress (deleted, dead-lettered via the redrive policy) without deserializing its body, guarding against allocation-DoS from oversized payloads.
Exceptions
- ArgumentOutOfRangeException
Thrown when
maxPayloadBytesis non-null and not positive.
UseMaxRetryAttempts(int)
Sets the foreground message bus send retry count and receive client SDK retry count.
IAwsSqsTransportBuilder UseMaxRetryAttempts(int maxRetryAttempts)
Parameters
maxRetryAttemptsintThe maximum retry count after the initial attempt (0 disables retries).
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Remarks
Framework message bus sends use a separate SDK client with both SDK retry counters disabled. An existing Dispatch retry owner supplies its own budget. Receive operations retain SDK retries.
Exceptions
- ArgumentOutOfRangeException
Thrown when
maxRetryAttemptsis negative.
UseRegion(string)
Configures the AWS region for the SQS client.
IAwsSqsTransportBuilder UseRegion(string region)
Parameters
regionstringThe AWS region identifier (e.g., "us-east-1").
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.UseRegion("us-east-1");
Remarks
The region must be a valid AWS region identifier. If not specified, the default region from the AWS SDK configuration will be used.
Exceptions
- ArgumentException
Thrown when
regionis null, empty, or whitespace.
UseRequestTimeout(TimeSpan)
Sets the total message bus send deadline and receive client SDK request timeout.
IAwsSqsTransportBuilder UseRequestTimeout(TimeSpan timeout)
Parameters
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Remarks
Message bus sends apply the deadline across all send attempts, including asynchronous SDK calls.
Receive operations map this setting to AmazonSQSConfig.Timeout.
Exceptions
- ArgumentOutOfRangeException
Thrown when
timeoutis not positive.
WithQueuePrefix(string)
Sets a prefix to apply to automatically generated queue names.
IAwsSqsTransportBuilder WithQueuePrefix(string prefix)
Parameters
prefixstringThe queue name prefix (e.g., "myapp-", "prod-").
Returns
- IAwsSqsTransportBuilder
The builder for fluent chaining.
Examples
sqs.WithQueuePrefix("myapp-prod-");
// Messages of type OrderCreated would go to "myapp-prod-ordercreated"
Remarks
The prefix is applied to queue names that are automatically derived from message type names, helping to organize queues by application or environment.
Exceptions
- ArgumentException
Thrown when
prefixis null, empty, or whitespace.