Configuration Options

CredentialSource

Mandatory

Default: AWS SDK credentials

By default the endpoint uses the SDK to retrieve AWS credentials. The AWS SDK permits a large number of transparent methods for configuring the credentials as outlined in the .NET SDK guidelines.

Example: To manually control the credentials retrieval, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.ClientFactory(() => new AmazonSQSClient(new InstanceProfileAWSCredentials()));

for S3 specify

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ClientFactory(() => new AmazonS3Client(new InstanceProfileAWSCredentials()));

Region

Mandatory

Default: AWS SDK region

By default the endpoint uses the SDK to retrieve the default AWS region from the AWS_REGION environment variable.

This is the Amazon Web Services Region in which to access the SQS service. The value must be a valid AWS region code.

Example: To manually control the region, specify

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.ClientFactory(() => new AmazonSQSClient(
    new AmazonSQSConfig { 
        RegionEndpoint = RegionEndpoint.APSoutheast2
    }));

for S3 specify

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ClientFactory(() => new AmazonS3Client(
    new AmazonS3Config
    {
        RegionEndpoint = RegionEndpoint.APSoutheast2
    }));

ProxyHost and ProxyPort

Optional

Default: Empty

This is the name of the host of the proxy server that the client must authenticate to.

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.ClientFactory(() => new AmazonSQSClient(
    new AmazonSQSConfig { 
        ProxyCredentials = new NetworkCredential(userName, password),
        ProxyHost = "127.0.0.1", 
        ProxyPort = 8888 
    }));

for S3 specify

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ClientFactory(() => new AmazonS3Client(
    new AmazonS3Config
    {
        ProxyCredentials = new NetworkCredential(userName, password),
        ProxyHost = "127.0.0.1",
        ProxyPort = 8888
    }));

Client

Optional

Default: new AmazonSQSClient()

By default the transport uses a parameterless constructor to build the SQS client. This overrides the default SQS client with a custom one.

Example: To use a custom client, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.ClientFactory(() => new AmazonSQSClient(new AmazonSQSConfig()));

Retention period

Optional

Default: 4 days

This is the maximum time that a message will be retained within SQS and S3. When a sent message is not received and successfully processed within the specified time, the message will be lost. This value applies to both SQS and S3 - messages in SQS will be deleted after this amount of time, and large message bodies stored in S3 will automatically be deleted after this amount of time.

The maximum value is 14 days.

Example: To set this to the maximum value, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.MaxTimeToLive(TimeSpan.FromDays(10));

Queue name prefix

Optional

Default: None

This string value is prepended to the name of every SQS queue referenced by the endpoint. This is useful when deploying many instances of the same application in the same AWS region (e.g. a development instance, a QA instance, and a production instance), and the queue names must be distinguished from each other.

Example: For a development instance, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.QueueNamePrefix("DEV-");

For example, queue names for the endpoint called "SampleEndpoint" might be:

DEV-SampleEndpoint
DEV-SampleEndpoint-Retries
DEV-SampleEndpoint-Timeouts
DEV-SampleEndpoint-TimeoutsDispatcher

Offload large messages to S3

Optional

Default: Disabled. Any attempt to send a message larger than the SQS limit will fail.

This option configures the S3 bucket to be used to store messages larger than 256 kB. If this option is not specified, S3 will not be used at all and any attempt to send a message larger than 256 kB will fail.

If the specified bucket doesn't exist, it will be created when the endpoint starts.

Example: To use a bucket named nsb-sqs-messages, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(
    bucketForLargeMessages: "nsb-sqs-messages",
    keyPrefix: "my/sample/path");

Key prefix

Mandatory

This is the path within the specified S3 bucket to store large messages.

S3 Client

Optional

Default: new AmazonS3Client()

By default, the transport uses a parameterless constructor to build the S3 client. This overrides the default S3 client with a custom one.

Example: To use a custom client, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ClientFactory(() => new AmazonS3Client(new AmazonS3Config()));

Encryption

Optional

Default: Disabled

Specifies how the large messages stored in S3 are to be encrypted. The default option is no encryption. The alternative is to use a managed encryption key:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ServerSideEncryption(ServerSideEncryptionMethod.AES256, keyManagementServiceKeyId: "keyId");

or to provide a custom key:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
var s3Configuration = transport.S3(bucketName, keyPrefix);
s3Configuration.ServerSideCustomerEncryption(ServerSideEncryptionCustomerMethod.AES256, "key", providedKeyMD5: "keyMD5");

Message visibility

The message visibility timeout in Amazon SQS defines how long a message remains hidden from other consumers after being received. If a handler takes longer to process a message than the configured visibility timeout, the message becomes visible again and may be reprocessed.

Without a message visibility extension mechanism (supported in version 7.3 and above), this can result in:

• Duplicate message processing, wasting resources
• Message deletion failures, causing the message to reappear on the queue
• Inaccurate delivery attempt counters, impacting poison message detection

To avoid these issues, configure the visibility timeout at the queue level, when creating, to at least match the maximum expected processing time of a message.

V1 Compatibility Mode

Optional

Default: Disabled

This option enables serialization of the TimeToBeReceived and ReplyToAddress message headers in the message envelope for compatibility with endpoints using version 1 of the transport.

Example: To enable version 1 compatibility, specify:

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.EnableV1CompatibilityMode();

Unrestricted Delayed Delivery

Optional

Default: disabled

SQS supports delaying message delivery by up to 15 minutes natively. To delay messages longer than 15 minutes, the unrestricted delayed delivery mode has to be enabled.

Example

var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.UnrestrictedDurationDelayedDelivery();

For a detailed overview about the unrestricted delayed delivery feature, refer to the delayed delivery documentation.