Getting Started

AWS Lambda with Simple Queue Service

NuGet Package: NServiceBus.AwsLambda.SQS (0.x)
Target Version: NServiceBus 7.x

Host NServiceBus endpoints with AWS Lambda using the Simple Queue Service as a trigger.

Basic usage

An NServiceBus endpoint is hosted in AWS Lambda by creating an AwsLambdaSQSEndpoint instance and calling the Process method from within an AWS Lambda definition.

AwsLambdaSQSEndpoint creation

The endpoint should be instantiated only once, when the lambda is first called, and assigned to a static field:

static readonly AwsLambdaSQSEndpoint endpoint = new AwsLambdaSQSEndpoint(context =>
    var endpointConfiguration = new AwsLambdaSQSEndpointConfiguration("AwsLambdaSQSTrigger");
    //customize configuration here

    return endpointConfiguration;

Since the cost of starting an AwsLambdaSQSEndpoint endpoint can be high, it is recommended to configure the lambda's concurrency to minimize cold starts.

Calling the Process method

The IAwsLambdaSQSEndpoint.Process method is invoked inside the function handler:

public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context)
    var cancellationDelay = context.RemainingTime.Subtract(TimeSpan.FromSeconds(10));
    using (var cancellationTokenSource = new CancellationTokenSource(cancellationDelay))
        await endpoint.Process(evnt, context, cancellationTokenSource.Token);

Queue creation

Transport installers are not supported. The creation of the required queues may be scripted using the CLI.



Specifying command routing for an AWS Lambda endpoint:

var transport = endpointConfiguration.Transport;
var routing = transport.Routing();
routing.RouteToEndpoint(typeof(ACommand), "<destination>");


NServiceBus startup diagnostics are disabled by default when using AWS Lambda. Diagnostics may be enabled as follows:

var advanced = endpointConfiguration.AdvancedConfiguration;

advanced.CustomDiagnosticsWriter(diagnostics =>
    return Task.CompletedTask;

Delayed Retries

Delayed retries are disabled by default when using AWS Lambdas. Delayed retries may be enabled as follows:

var recoverability = endpointConfiguration.AdvancedConfiguration.Recoverability();
recoverability.Delayed(customization =>

If the accumulated time increase is expected to be greater than 15 minutes, UnrestrictedDurationDelayedDelivery must be enabled:

Automatic creation of the required queues for unrestricted delayed delivery is not supported. The creation of the required queues may be scripted using the CLI.

Error queue

Messages which fail all retries are moved to the error queue, which must be defined as follows:

var advanced = endpointConfiguration.AdvancedConfiguration;


Alternatively, the endpoint may be configured to never move failing messages to the error queue as follows:



The default serializer is the XmlSerializer. A different serializer can be configured:



The license is provided via the NSERVICEBUS_LICENSE environment variable, which can be set via the Function settings in the Lambda console.

Native integration

It is sometimes useful to access the native Amazon SQS message from behaviors and handlers. In addition to SqsTransport's support for Amazon SQS Native Integration, AwsLambdaSQSEndpoint also provides access to an instance of the native Lambda message type SQSEvent.SQSMessage from the message processing context.

public class AccessToLambdaNativeMessageInHandler : IHandleMessages<TestMessage>
  public Task Handle(TestMessage message, IMessageHandlerContext context)
    var nativeMessage = context.Extensions.Get<SQSEvent.SQSMessage>();

    return Task.CompletedTask;

Supported features

The AwsLambdaSQSEndpoint class supports the full feature set of NServiceBus including:

  • Outbox
  • Sagas
  • Delayed Delivery
  • Recoverability
  • Publish / Subscribe

Persistence is required to use some of these features.


As the AwsLambdaSQSEndpoint uses the SqsTransport, it only supports the Receive Only and Disabled transaction modes.


Last modified