Table of Contents

Interface IAwsSqsTransportBuilder

Namespace
Excalibur.Dispatch.Transport.Aws
Assembly
Excalibur.Dispatch.Transport.AwsSqs.dll

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

configure Action<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 configure is null.

ConfigureFifo(Action<IAwsSqsFifoBuilder>)

Configures the FIFO queue settings using a fluent builder.

IAwsSqsTransportBuilder ConfigureFifo(Action<IAwsSqsFifoBuilder> configure)

Parameters

configure Action<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 .fifo suffix
  • A message group ID selector is required
  • Either content-based deduplication or a deduplication ID selector is required

Exceptions

ArgumentNullException

Thrown when configure is null.

ConfigureProvisioning(Action<AwsSqsProvisioningOptions>)

Configures optional, opt-in startup provisioning of dead-letter redrive policies and SNS subscriptions.

IAwsSqsTransportBuilder ConfigureProvisioning(Action<AwsSqsProvisioningOptions> configure)

Parameters

configure Action<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 configure is null.

ConfigureQueue(Action<IAwsSqsQueueBuilder>)

Configures the standard SQS queue settings using a fluent builder.

IAwsSqsTransportBuilder ConfigureQueue(Action<IAwsSqsQueueBuilder> configure)

Parameters

configure Action<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 configure is null.

ConfigureSns(Action<IAwsSqsSnsBuilder>)

Configures SNS topic integration using a fluent builder.

IAwsSqsTransportBuilder ConfigureSns(Action<IAwsSqsSnsBuilder> configure)

Parameters

configure Action<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 configure is null.

ConfigureVisibilityHeartbeat(Action<AwsSqsVisibilityHeartbeatOptions>)

Configures the in-flight visibility-timeout heartbeat for the wired subscriber.

IAwsSqsTransportBuilder ConfigureVisibilityHeartbeat(Action<AwsSqsVisibilityHeartbeatOptions> configure)

Parameters

configure Action<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 configure is null.

MapQueue<TMessage>(string)

Maps a message type to a specific queue URL.

IAwsSqsTransportBuilder MapQueue<TMessage>(string queueUrl) where TMessage : class

Parameters

queueUrl string

The SQS queue URL for this message type.

Returns

IAwsSqsTransportBuilder

The builder for fluent chaining.

Type Parameters

TMessage

The 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 queueUrl is 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

maxPayloadBytes int?

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 maxPayloadBytes is 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

maxRetryAttempts int

The 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 maxRetryAttempts is negative.

UseRegion(string)

Configures the AWS region for the SQS client.

IAwsSqsTransportBuilder UseRegion(string region)

Parameters

region string

The 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 region is null, empty, or whitespace.

UseRequestTimeout(TimeSpan)

Sets the total message bus send deadline and receive client SDK request timeout.

IAwsSqsTransportBuilder UseRequestTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

The request timeout. Must be greater than Zero.

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 timeout is not positive.

WithQueuePrefix(string)

Sets a prefix to apply to automatically generated queue names.

IAwsSqsTransportBuilder WithQueuePrefix(string prefix)

Parameters

prefix string

The 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 prefix is null, empty, or whitespace.