Shuttle.Hopper.AmazonSqs 21.0.1-beta

Amazon SQS

Amazon Simple Queue Service (SQS) implementation for use with Shuttle.Hopper, providing reliable message queuing capabilities using AWS SQS.

In order to make use of the AmazonSqsQueue you will need access to an Amazon Web Services account. There are some options for local development, such as ElasticMQ, which are beyond the scope of this documentation.

You may also want to take a look at Messaging Using Amazon SQS.

Installation

dotnet add package Shuttle.Hopper.AmazonSqs

Configuration

The URI structure is amazonsqs://configuration-name/queue-name.

Programmatic Configuration

services.AddHopper(hopperBuilder =>
{
    hopperBuilder.UseAmazonSqs(builder =>
    {
        var amazonSqsOptions = new AmazonSqsOptions
        {
            AwsCredentials = new BasicAWSCredentials("accessKey", "secretKey"),
            AmazonSqsConfig = new AmazonSQSConfig
            {
                ServiceURL = "http://localhost:9324",
                AuthenticationRegion = "us-east-1"
            },
            MaxMessages = 5,
            WaitTime = TimeSpan.FromSeconds(20)
        };

        builder.AddOptions("local", amazonSqsOptions);
    });
});

JSON Configuration

The default JSON settings structure is as follows:

{
  "Shuttle": {
    "AmazonSqs": {
      "local": {
        "MaxMessages": 5,
        "WaitTime": "00:00:20",
        "AmazonSqsConfig": {
          "ServiceURL": "http://localhost:9324"
        }
      },
      "production": {
        "MaxMessages": 10,
        "WaitTime": "00:00:20",
        "AmazonSqsConfig": {
          "ServiceURL": "https://sqs.us-east-2.amazonaws.com/123456789012/MyQueue"
        }
      }
    }
  }
}

URI Format Examples

amazonsqs://local/my-queue
amazonsqs://production/order-processing-queue

The configuration name (e.g., local, production) must match a configuration defined via AddOptions().

Options

Authentication

AWS credentials can be configured in several ways:

Programmatic Credentials

amazonSqsOptions.AwsCredentials = new BasicAWSCredentials("accessKey", "secretKey");

Environment Variables

If AwsCredentials is not set, the AWS SDK will automatically use credentials from:

• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
• AWS credentials file (~/.aws/credentials)
• IAM role (when running on EC2 or ECS)

IAM Roles (Recommended for Production)

When running on AWS infrastructure, use IAM roles instead of hardcoded credentials.

Troubleshooting

Queue URL Not Resolved

If you see errors about unresolved queue URLs, ensure:

1. The queue exists in your AWS account
2. The configuration name in the URI matches your configured options
3. Your AWS credentials have permission to access the queue

Authentication Errors

If you encounter authentication errors:

1. Verify your AWS credentials are correct
2. Check that the AuthenticationRegion matches your queue's region
3. Ensure your IAM user/role has the necessary SQS permissions

Configuration Name Mismatch

The configuration name in the URI (e.g., amazonsqs://local/queue-name) must exactly match a configuration added via builder.AddOptions("local", ...). Configuration names are case-sensitive.