# AWS Lambda with Simple Queue Service


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 is created, configured, and registered as singleton in the service collection, at startup when the lambda is first instantiated:

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

```cs
[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAwsLambdaSQSEndpoint("endpoint-name", (endpointConfiguration, _) =>
        {
            endpointConfiguration.UseSerialization<SystemJsonSerializer>();

            //additional endpoint configuration
        });
    }
}
```

<!-- 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
[LambdaFunction]
[SQSEvent("arn:aws:sqs:region:account:endpoint-name")]
public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context)
{
    using var cancellationTokenSource =
        new CancellationTokenSource(context.RemainingTime.Subtract(DefaultRemainingTimeGracePeriod));

    await serverlessEndpoint.Process(evnt, context, cancellationTokenSource.Token);
}

static readonly TimeSpan DefaultRemainingTimeGracePeriod = TimeSpan.FromSeconds(10);
```

<!-- 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

A serializer must be configured:

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

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

<!-- endsnippet -->

### Registering services

If handlers, behaviors, or other endpoint components need custom dependencies, register them with `AwsLambdaSQSEndpointConfiguration.RegisterServices` while configuring the endpoint:

<!-- snippet: aws-register-services -->

```cs
endpointConfiguration.RegisterServices(services =>
{
    services.AddSingleton<MyDependency>();
});
```

<!-- endsnippet -->

For Lambdas that use `AddAwsLambdaSQSEndpoint`, register endpoint dependencies inside the configuration callback rather than on the application's root `IServiceCollection`.


### 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 -->



### 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.