Define Lambda function handler in C#

The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.

When your function is invoked and Lambda runs your function's handler method, it passes two arguments to your function. The first argument is the event object. When another AWS service invokes your function, the event object contains data about the event that caused your function to be invoked. For example, an event object from API Gateway contains information about the path, HTTP method, and HTTP headers. The exact event structure varies according to the AWS service invoking your function. See Invoking Lambda with events from other AWS services for more information about event formats for individual services.

Lambda also passes a context object to your function. This object contains information about the invocation, function, and execution environment. For more information, see Using the Lambda context object to retrieve C# function information.

The native format for all Lambda events is streams of bytes representing the JSON formatted event. Unless your function input and output parameters are of type System.IO.Stream, you must serialize them. Specify the serializer you want to use by setting the LambdaSerializer assembly attribute. For more information, see Serialization in Lambda functions.

.NET execution models for Lambda

There are two different execution models for running Lambda functions in .NET: the class library approach and the executable assembly approach.

In the class library approach, you provide Lambda with a string indicating the AssemblyName, ClassName, and Method of the function to be invoked. For more information about the format of this string, see Class library handlers. During the function's initialization phase, your function's class is initialized, and any code in the constructor is run.

In the executable assembly approach, you use C# 9's top-level statements feature. This approach generates an executable assembly which Lambda runs whenever it receives an invoke command for your function. You provide Lambda only with the name of the executable assembly to run.

The following sections give example function code for these two approaches.

Class library handlers

The following Lambda function code shows an example of a handler method (FunctionHandler) for a Lambda function which uses the class library approach. In this example funtion, Lambda receives an event from API Gateway that invokes the function. The function reads a record from a database and returns the record as part of the API Gateway response.

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord)
        };
    }
}

When you create a Lambda function, you need to provide Lambda with information about your function's handler in the form of a handler string. This tells Lambda which method in your code to run when your function is invoked. In C#, the format of the handler string when using the class library approach is as follows:

ASSEMBLY::TYPE::METHOD, where:

For the example code shown, if the assembly is named GetProductHandler, then the handler string would be GetProductHandler::GetProductHandler.Function::FunctionHandler.

Executable assembly handlers

In the following example, the Lambda function is defined as an executable assembly. The handler method in this code is named Handler. When using executable assemblies, the Lambda runtime must be bootstrapped. To do this, you use the LambdaBootstrapBuilder.Create method. This method takes as inputs the method your function uses as the handler and the Lambda serializer to use.

For more information about using top-level statements, see Introducing the .NET 6 runtime for AWS Lambda on the AWS compute blog.

namespace GetProductHandler;

IDatabaseRepository repo = new DatabaseRepository();

await LambdaBootstrapBuilder.Create<APIGatewayProxyRequest>(Handler, new DefaultLambdaJsonSerializer())
    .Build()
    .RunAsync();

async Task<APIGatewayProxyResponse> Handler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
{
    var id = apigProxyEvent.PathParameters["id"];
        
    var databaseRecord = await this.repo.GetById(id);
    
    return new APIGatewayProxyResponse 
    {
        StatusCode = (int)HttpStatusCode.OK,
        Body = JsonSerializer.Serialize(databaseRecord)
    };
};

When using executable assemblies, the handler string that tells Lambda how to run your code is the name of the assembly. In this example, that would be GetProductHandler.

Serialization in Lambda functions

If your Lambda function uses input or output types other than a Stream object, you must add a serialization library to your application. You can implement serialization either using the standard reflection based serialization provided by System.Text.Json and Newtonsoft.Json, or by using source generated serialization.

Using source generated serialization

Source generated serialization is a feature of .NET versions 6 and later that allows serialization code to be generated at compile time. It removes the need for reflection and can improve the performance of your function. To use source generated serialization in your function, do the following:

An example function using source generated serialization is shown in the following code.

[assembly: LambdaSerializer(typeof(SourceGeneratorLambdaJsonSerializer<CustomSerializer>))]

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function()
    {
        this._repo = new DatabaseRepository();
    }
    
    public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest request)
    {
        var id = request.PathParameters["id"];
        
        var databaseRecord = await this._repo.GetById(id);
        
        return new APIGatewayProxyResponse 
        {
            StatusCode = (int)HttpStatusCode.OK,
            Body = JsonSerializer.Serialize(databaseRecord, CustomSerializer.Default.Product)
        };
    }
}

[JsonSerializable(typeof(APIGatewayProxyRequest))]
[JsonSerializable(typeof(APIGatewayProxyResponse))]
[JsonSerializable(typeof(Product))]
public partial class CustomSerializer : JsonSerializerContext
{
    
}

Using reflection-based serialization

AWS provides pre-built libraries to let you quickly add serialization to your application. You configure this using either the Amazon.Lambda.Serialization.SystemTextJson or Amazon.Lambda.Serialization.Json NuGet packages. Behind the scenes, Amazon.Lambda.Serialization.SystemTextJson uses System.Text.Json to perform serialization tasks, and Amazon.Lambda.Serialization.Json uses the Newtonsoft.Json package.

You can also create your own serialization library by implementing the ILambdaSerializer interface, which is available as part of the Amazon.Lambda.Core library. This interface defines two methods:

Simplify function code with the Lambda Annotations framework

Lambda Annotations is a framework for .NET 6 and .NET 8 which simplifies writing Lambda functions using C#. With the Annotations framework, you can replace much of the code in a Lambda function written using the regular programming model. Code written using the framework uses simpler expressions that allow you to focus on your business logic.

The following example code shows how using the annotations framework can simplify writing Lambda functions. The first example shows code written using the regular Lambda program model, and the second shows the equivalent using the Annotations framework.

public APIGatewayHttpApiV2ProxyResponse LambdaMathAdd(APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context)
{
    if (!request.PathParameters.TryGetValue("x", out var xs))
    {
        return new APIGatewayHttpApiV2ProxyResponse
        {
            StatusCode = (int)HttpStatusCode.BadRequest
        };
    }
    if (!request.PathParameters.TryGetValue("y", out var ys))
    {
        return new APIGatewayHttpApiV2ProxyResponse
        {
            StatusCode = (int)HttpStatusCode.BadRequest
        };
    }
    var x = int.Parse(xs);
    var y = int.Parse(ys);
    return new APIGatewayHttpApiV2ProxyResponse
    {
        StatusCode = (int)HttpStatusCode.OK,
        Body = (x + y).ToString(),
        Headers = new Dictionary≪string, string> { { "Content-Type", "text/plain" } }
    };
}

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/add/{x}/{y}")]
public int Add(int x, int y)
{
    return x + y;
}

For another example of how using Lambda Annotations can simplify your code, see this cross-service example application in the awsdocs/aws-doc-sdk-examples GitHub repository. The folder PamApiAnnotations uses Lambda Annotations in the main function.cs file. For comparison, the PamApi folder has equivalent files written using the regular Lambda programming model.

The Annotations framework uses source generators to generate code that translates from the Lambda programming model to the code seen in the second example.

For more information about how to use Lambda Annotations for .NET, see the following resources:

Dependency injection with Lambda Annotations framework

You can also use the Lambda Annotations framework to add dependency injection to your Lambda functions using syntax you are familiar with. When you add a [LambdaStartup] attribute to a Startup.cs file, the Lambda Annotations framework will generate the required code at compile time.

[LambdaStartup]
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddSingleton<IDatabaseRepository, DatabaseRepository>();
    }
}

Your Lambda function can inject services using either constructor injection or by injecting into individual methods using the [FromServices] attribute.

[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace GetProductHandler;

public class Function
{
    private readonly IDatabaseRepository _repo;
    
    public Function(IDatabaseRepository repo)
    {
        this._repo = repo;
    }
    
    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/product/{id}")]
    public async Task<Product> FunctionHandler([FromServices] IDatabaseRepository repository, string id)
    {
        return await this._repo.GetById(id);
    }
}

Lambda function handler restrictions

Note that there are some restrictions on the handler signature.

Code best practices for C# Lambda functions

Adhere to the guidelines in the following list to use best coding practices when building your Lambda functions: