Getting Started

AWS Lambda with Simple Queue Service

NuGet Package: NServiceBus.AwsLambda.SQS (1.x)
Target Version: NServiceBus 8.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.


The configuration API exposes NServiceBus configuration options to allow customization; however, not all options will be applicable to execution within AWS Lambda.


Specifying command routing for an AWS Lambda endpoint:

var routing = endpointConfiguration.RoutingSettings;
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, token) =>
  return Task.CompletedTask;

Delayed Retries

Delayed retries are disabled by default when using AWS Lambda. Delayed retries cam be enabled as follows:

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

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:

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.


Related Articles

Last modified