# AWS Lambda with Simple Queue Service

<!-- Version variant: sqslambda_1; default: [/nservicebus/hosting/aws-lambda-simple-queue-service/index.md](/nservicebus/hosting/aws-lambda-simple-queue-service/index.md) -->


Host NServiceBus endpoints with [AWS Lambda](https://aws.amazon.com/lambda/) using the [Simple Queue Service](https://aws.amazon.com/sqs/) 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. An AWS Lambda application currently supports one NServiceBus endpoint.

Support for multiple endpoints in a single Lambda application is being considered. If multi-endpoint support would be valuable, [add a thumbs-up or share the use case on issue #681](https://github.com/Particular/NServiceBus.AwsLambda.Sqs/issues/681).

### `AwsLambdaSQSEndpoint` creation

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

<!-- snippet: aws-endpoint-creation -->

```cs
static readonly AwsLambdaSQSEndpoint endpoint = new AwsLambdaSQSEndpoint(context =>
{
    var endpointConfiguration = new AwsLambdaSQSEndpointConfiguration("AwsLambdaSQSTrigger");

    //customize configuration here

    return endpointConfiguration;
});
```

<!-- endsnippet -->


Since the cost of starting an `AwsLambdaSQSEndpoint` endpoint can be high, it is recommended to [configure the lambda's concurrency](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html) to minimize cold starts.

### Calling the `Process` method

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

<!-- snippet: aws-function-definition -->

```cs
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);
}
```

<!-- endsnippet -->

### Queue creation

Transport installers are not supported. The creation of the required queues may be scripted using the [CLI](/transports/sqs/operations-scripting.md#create-resources).

## Configuration

The configuration API exposes NServiceBus configuration options to allow customization; however, not all options will [apply to execution within AWS Lambda](analyzers.md).

### Serializer

The default serializer is the [XmlSerializer](/nservicebus/serialization/xml.md). A different serializer can be configured:

<!-- snippet: aws-custom-serializer -->

```cs
endpointConfiguration.UseSerialization<SystemJsonSerializer>();
```

<!-- endsnippet -->



### Routing

Specifying [command routing](/nservicebus/messaging/routing.md#command-routing) for an AWS Lambda endpoint:

<!-- snippet: aws-configure-routing -->

```cs
var routing = endpointConfiguration.RoutingSettings;
routing.RouteToEndpoint(typeof(ACommand), "<destination>");
```

<!-- endsnippet -->

### Diagnostics

[NServiceBus startup diagnostics](/nservicebus/hosting/startup-diagnostics.md) are disabled by default when using AWS Lambda. Diagnostics may be enabled as follows:

<!-- snippet: aws-custom-diagnostics -->

```cs
var advanced = endpointConfiguration.AdvancedConfiguration;

advanced.CustomDiagnosticsWriter((diagnostics, token) =>
{
    context.Logger.LogLine(diagnostics);
    return Task.CompletedTask;
});
```

<!-- endsnippet -->

### Delayed Retries

[Delayed retries](/nservicebus/recoverability/configure-delayed-retries.md) are disabled by default when using AWS Lambda. Delayed retries can be enabled as follows:

<!-- snippet: aws-delayed-retries -->

```cs
var recoverability = endpointConfiguration.AdvancedConfiguration.Recoverability();
recoverability.Delayed(customization =>
{
    customization.NumberOfRetries(5);
    customization.TimeIncrease(TimeSpan.FromSeconds(15));
});
```

<!-- endsnippet -->


### Error handling

Messages that fail all retries are [moved to the error queue](/nservicebus/recoverability/configure-error-handling.md#configure-the-error-queue-address). Alternatively, to enable the use of [AWS Lambda error handling](https://docs.aws.amazon.com/lambda/latest/dg/invocation-retries.html), the endpoint can be configured to not move messages to the error queue:

<!-- snippet: aws-configure-dont-move-to-error -->

```cs
endpointConfiguration.DoNotSendMessagesToErrorQueue();
```

<!-- endsnippet -->

### Licenses

The license is provided via the `PARTICULARSOFTWARE_LICENSE` (with a fallback to `NSERVICEBUS_LICENSE` for backward compatibility reasons) environment variable, which can be set via the Function settings in the [Lambda console](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html).

## 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](/transports/sqs/native-integration.md), `AwsLambdaSQSEndpoint` also provides access to an instance of the native Lambda message type `SQSEvent.SQSMessage` from the message processing context.

<!-- snippet: native-lambda-sqs-message -->

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

    return Task.CompletedTask;
  }
}
```

<!-- endsnippet -->

## Supported features

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

* [Outbox](/nservicebus/outbox/index.md)
* [Sagas](/nservicebus/sagas/index.md)
* [Delayed Delivery](/nservicebus/messaging/delayed-delivery.md)
* [Recoverability](/nservicebus/recoverability/index.md)
* [Publish / Subscribe](/nservicebus/messaging/publish-subscribe/index.md)

[Persistence](/persistence/index.md) is required to use some of these features.

### Transactions

The `AwsLambdaSQSEndpoint` uses `SqsTransport`, which limits transaction support to the Receive Only and Disabled [transaction modes](/transports/transactions.md). Distributed transactions and atomic send-and-receive semantics are not available with this transport.