Getting Started

Simple AmazonSQS Transport usage

NuGet Package: NServiceBus.AmazonSQS (4.x)
Target Version: NServiceBus 7.x

This sample shows basic usage of SQS as a transport for NServiceBus. The application sends an empty message to itself via the SQS transport, and writes a message to the console when the message is received.

AWS setup

Security and access configuration

Add the AWS Access Key ID and AWS Secret Access Key to the following environment variables:

  • Access Key ID in AWS_ACCESS_KEY_ID
  • Secret Access Key in AWS_SECRET_ACCESS_KEY
  • Default Region in AWS_REGION

See also AWS Account Identifiers, Managing Access Keys for an AWS Account, and IAM Security Credentials.

See also AWS Regions for a list of available regions.


Several Amazon SQS queues are required to run this sample. These will be created at start-up via the installer mechanism of NServiceBus. The queues can be seen in the SQS management UI.

  • Samples-Sqs-Simple: The main message processing queue.
  • Samples-Sqs-Simple-Retries: Queue used for delayed retries.
  • error: Queue used for error handling.


An Amazon S3 bucket is required to leverage the S3 bucket For large messages feature of the SQS transport. Create an S3 bucket and replace the bucketname in the sample startup with the the name of the created bucket.

Endpoint configuration

Configure the endpoint to use the SQS transport.

var endpointConfiguration = new EndpointConfiguration("Samples.Sqs.Simple");
var transport = endpointConfiguration.UseTransport<SqsTransport>();
transport.S3("bucketname", "my/key/prefix");

Run the sample

Start the endpoint. A message will be sent and received by a handler.

View a message in transit

At startup the endpoint will send two messages. One is a message that falls under the 256kb size limit. The other is above that limit and will leverage the S3 bucket for large messages feature of the SQS transport.

var myMessage = new MyMessage();
await endpointInstance.SendLocal(myMessage)

var myLargeMessage = new MyMessage
    Data = new byte[257 * 1024]
await endpointInstance.SendLocal(myLargeMessage)

To view a message in transit change the endpoint to be send-only. There is commented out code already in this samples configuration.

//TODO: uncomment to view a message in transit

Start the endpoint. Since the endpoint is now send-only, the messages are written to SQS but not dequeued. The message can now be viewed in the SQS management UI.

The large message contents can be be viewed in the S3 management UI.

See also Receiving and Deleting a Message from an Amazon SQS Queue.

Related Articles

Last modified