Deploy .NET Lambda functions with container images

You can deploy your Lambda function code as a container image. To help you build a container image for your .NET function, AWS provides the following resources:

• AWS base images for Lambda

  These base images are preloaded with a language runtime and other components that are required to run the image on Lambda. AWS provides a Dockerfile for each of the base images to help with building your container image.

• Open-source runtime interface clients

  If you use a community or private enterprise base image, you must add a runtime interface client to the base image to make it compatible with Lambda.

• Open-source runtime interface emulator

  Lambda provides a runtime interface emulator (RIE) for you to test your function locally. The base images for Lambda and base images for custom .runtimes include the RIE. For other base images, you can download the RIE for testing your image locally.

The workflow for a function defined as a container image includes these steps:

1. Build your container image using the resources listed in this topic.

2. Upload the image to your Amazon Elastic Container Registry (Amazon ECR) container registry.

3. Create the function or update the function code to deploy the image to an existing function.

AWS base images for .NET

AWS provides the following base images for .NET:

Tags	Runtime	Operating system	Dockerfile	Deprecation
core3.1	.NET Core 3.1	Amazon Linux 2	Dockerfile for .NET Core 3.1 on GitHub	Apr 3, 2023
6	.NET 6	Amazon Linux 2	Dockerfile for .NET 6 on GitHub
5.0	.NET 5	Amazon Linux 2	Dockerfile for .NET 5 on GitHub

Amazon ECR repository: gallery.ecr.aws/lambda/dotnet

Using a .NET base image

Prerequisites

To complete the steps in this section, you must have the following:

• .NET SDK – The following steps use the .NET 7 base image. Make sure that your .NET version matches the version of the base image that you specify in your Dockerfile.

• Docker

Creating and deploying an image using a base image

In the following steps, you use Amazon.Lambda.Templates and Amazon.Lambda.Tools to create a .NET project. Then, you build a Docker image, upload the image to Amazon ECR, and deploy it to a Lambda function.

1. Install the Amazon.Lambda.Templates NuGet package.

   dotnet new install Amazon.Lambda.Templates

   For more information about this package, see the AWS Lambda for .NET Core repository on GitHub.

2. Create a .NET project using the lambda.image.EmptyFunction template.

   dotnet new lambda.image.EmptyFunction --name MyFunction --region us-east-1

3. In the src/MyFunction directory, examine the following files:

   • aws-lambda-tools-defaults.json – This file is where you specify the command line options when deploying your Lambda function.

   • Function.cs – Your Lambda handler function code. This is a C# template that includes the default Amazon.Lambda.Core library and a default LambdaSerializer attribute. For more information about serialization requirements and options, see Serializing Lambda functions. You can use the provided code for testing, or replace it with your own.

   • MyFunction.csproj – A .NET project file, which lists the files and assemblies that comprise your application.

   • Readme – This file contains more information about the sample Lambda function.

4. Examine the Dockerfile in the src/MyFunction directory. You can use the provided Dockerfile for testing, or replace it with your own. If you use your own, make sure to:

   • Set the FROM property to the URI of the base image. Your .NET version must match the version of the base image.

   • Set the CMD argument to the Lambda function handler. This should match the image-command in aws-lambda-tools-defaults.json.

   Example Dockerfile

   FROM public.ecr.aws/lambda/dotnet:7
   #You can also pull these images from DockerHub amazon/aws-lambda-dotnet:7
     
   # Copy function code
   COPY publish/* ${LAMBDA_TASK_ROOT}
     
   # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)
   CMD [ "MyProject::MyFunction.Function::FunctionHandler" ]

5. Install the Amazon.Lambda.Tools .NET Core Global Tool.

   dotnet tool install -g Amazon.Lambda.Tools

   If Amazon.Lambda.Tools is already installed, make sure that you have the latest version.

   dotnet tool update -g Amazon.Lambda.Tools

6. Change the directory to MyFunction/src/MyFunction, if you're not there already.

   cd src/MyFunction

7. Use Amazon.Lambda.Tools to build the Docker image, push it to a new Amazon ECR repository, and deploy the Lambda function.

   For --function-role, specify the role name—not the Amazon Resource Name (ARN)—of the execution role for the function. For example, lambda-role.

   dotnet lambda deploy-function MyFunction --function-role lambda-role

   For more information about the Amazon.Lambda.Tools .NET Core Global Tool, see the AWS Extensions for .NET CLI repository on GitHub.

8. Invoke the function.

   dotnet lambda invoke-function MyFunction --payload "Testing the function"

   If everything is successful, you see the following:

   Payload:
   "TESTING THE FUNCTION"
   
   Log Tail:
   START RequestId: id Version: $LATEST
   END RequestId: id
   REPORT RequestId: id  Duration: 0.99 ms       Billed Duration: 1 ms         Memory Size: 256 MB     Max Memory Used: 12 MB

.NET runtime interface clients

You can download the .NET runtime interface client from the AWS Lambda for .NET Core repository on GitHub.