Transports AWS SQS

AWS SQS Transport

Fully managed message queuing service for distributed data mapping with AWS infrastructure.

Overview

FxMap.Aws.Sqs integrates Amazon SQS with the FxMap framework, enabling efficient data transportation between distributed systems using SQS as the underlying communication layer.

SQS-Based Communication

Long polling and batch processing for efficient message handling

Automatic Queue Management

Creates queues following naming pattern: fxmap-{key-namespace}-{key-type-name}

Multiple Auth Methods

Supports credentials, IAM roles, and LocalStack for testing

Installation

dotnet add package FxMap.Aws.Sqs

Or via Package Manager Console:

Install-Package FxMap.Aws.Sqs

Supported .NET versions: 8.0 and 9.0

Configuration

Standard AWS Setup with Credentials

Configure AWS SQS transport with explicit credentials:

using FxMap;
using FxMap.Aws.Sqs;
using Amazon;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddFxMap(cfg =>
{
    cfg.AddEntitiesFromAssemblyContaining<SomeEntityAssemblyMarker>();
    cfg.AddSqs(sqs =>
    {
        sqs.Region(RegionEndpoint.USEast1, credential =>
        {
            credential.AccessKeyId("your-access-key-id");
            credential.SecretAccessKey("your-secret-access-key");
        });
    });
});
 
var app = builder.Build();
app.Run();

IAM Role Authentication (Recommended)

When running on AWS infrastructure (EC2, ECS, Lambda), use IAM roles for automatic credential management:

builder.Services.AddFxMap(cfg =>
{
    cfg.AddEntitiesFromAssemblyContaining<SomeEntityAssemblyMarker>();
    cfg.AddSqs(sqs =>
    {
        // No explicit credentials needed - uses IAM role
        sqs.Region(RegionEndpoint.USEast1);
    });
});

LocalStack for Testing

Use LocalStack to test SQS functionality locally without AWS:

builder.Services.AddFxMap(cfg =>
{
    cfg.AddEntitiesFromAssemblyContaining<SomeEntityAssemblyMarker>();
    cfg.AddSqs(sqs =>
    {
        sqs.Region(RegionEndpoint.USEast1, credential =>
        {
            credential.ServiceUrl("http://localhost:4566");
            credential.AccessKeyId("test");
            credential.SecretAccessKey("test");
        });
    });
});

Using Configuration

builder.Services.AddFxMap(cfg =>
{
    cfg.AddEntitiesFromAssemblyContaining<SomeEntityAssemblyMarker>();
    cfg.AddSqs(sqs =>
    {
        var region = RegionEndpoint.GetBySystemName(
            builder.Configuration["AWS:Region"] ?? "us-east-1"
        );
 
        sqs.Region(region, credential =>
        {
            credential.AccessKeyId(builder.Configuration["AWS:AccessKeyId"]);
            credential.SecretAccessKey(builder.Configuration["AWS:SecretAccessKey"]);
        });
    });
});

Queue Naming Convention

FxMap automatically creates and manages SQS queues with a specific naming pattern:

Request Queues

fxmap-{key-namespace}-{key-type-name}

Built from the namespace and name of the distributed key type, lowercased, with dots turned into dashes. Example for MyApp.Keys.UserDistributedKey: fxmap-myapp-keys-userdistributedkey

Response Queues

fxmap-response-{machinename}-{guid}

Example: fxmap-response-webserver1-a1b2c3d4

Important Note

Avoid creating queues with names matching FxMap's reserved patterns to prevent conflicts with the framework's automated queue management.

Server: the service that owns the data

Register the entities and a data provider as usual, and add SQS. The service polls the request queue of each distributed key it owns, and no endpoint is needed:

using Amazon;
 
builder.Services.AddFxMap(cfg =>
    {
        cfg.AddEntitiesFromAssemblyContaining<UserConfig>();
        cfg.AddSqs(sqs => sqs.Region(RegionEndpoint.USEast1));
    })
    .AddEntityFrameworkCore(c => c.AddDbContexts(typeof(UserDbContext)));

Best Practices

Use IAM Roles in Production

Prefer IAM role-based authentication over hard-coded credentials for better security

Configure Dead Letter Queues

Set up DLQs in AWS console for handling failed messages and debugging

Monitor Queue Metrics

Use CloudWatch to monitor queue depth, message age, and processing rates

Test with LocalStack

Use LocalStack for local development and testing before deploying to AWS

---

Source: https://fxmapper.net/docs/transports/aws-sqs/ — the website is always the most up to date version.