Deploy .NET Lambda functions with container images - AWS Lambda
AWS base images for .NETUsing an AWS base imageUsing a non-AWS base image

Deploy .NET Lambda functions with container images

There are three ways to build a container image for a .NET Lambda function:

Tip

To reduce the time it takes for Lambda container functions to become active, see Use multi-stage builds in the Docker documentation. To build efficient container images, follow the Best practices for writing Dockerfiles.

This page explains how to build, test, and deploy container images for Lambda.

AWS base images for .NET

AWS provides the following base images for .NET:

Tags Runtime Operating system Dockerfile Deprecation

8

 .NET 8 Amazon Linux 2023 Dockerfile for .NET 8 on GitHub

Not scheduled

6

 .NET 6 Amazon Linux 2 Dockerfile for .NET 6 on GitHub

Dec 20, 2024

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

Using an AWS base image for .NET

Prerequisites

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

  • .NET SDK – The following steps use the .NET 8 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

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

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

  3. Navigate to the MyFunction/src/MyFunction directory. This is where the project files are stored. 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 Serialization in 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.md – 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.

    Note that the example Dockerfile does not include a USER instruction. When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to the root user when no USER instruction is provided.

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

  5. Install the Amazon.Lambda.Tools .NET 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 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

  9. Delete the Lambda function.

    dotnet lambda delete-function MyFunction

Using an alternative base image with the runtime interface client

If you use an OS-only base image or an alternative base image, you must include the runtime interface client in your image. The runtime interface client extends the Using the Lambda runtime API for custom runtimes, which manages the interaction between Lambda and your function code.

The following example demonstrates how to build a container image for .NET using a non-AWS base image, and how to add the Amazon.Lambda.RuntimeSupport package, which is the Lambda runtime interface client for .NET. The example Dockerfile uses the Microsoft .NET 8 base image.

Prerequisites

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

  • .NET SDK – The following steps use a .NET 8 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 an alternative base image

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

    dotnet new install Amazon.Lambda.Templates

  2. Create a .NET project using the lambda.CustomRuntimeFunction template. This template includes the Amazon.Lambda.RuntimeSupport package.

    dotnet new lambda.CustomRuntimeFunction --name MyFunction --region us-east-1

  3. Navigate to the MyFunction/src/MyFunction directory. This is where the project files are stored. 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 – The code contains a class with a Main method that initializes the Amazon.Lambda.RuntimeSupport library as the bootstrap. The Main method is the entry point for the function's process. The Main method wraps the function handler in a wrapper that the bootstrap can work with. For more information, see Using Amazon.Lambda.RuntimeSupport as a class library in the GitHub repository.

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

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

  4. Open the aws-lambda-tools-defaults.json file and Add the following lines:

      "package-type": "image",
  "docker-host-build-output-dir": "./bin/Release/lambda-publish"

    • package-type: Defines the deployment package as a container image.

    • docker-host-build-output-dir: Sets the output directory for the build process.

    Example aws-lambda-tools-defaults.json
    {
  "Information": [
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",
    "dotnet lambda help",
    "All the command line options for the Lambda command can be specified in this file."
  ],
  "profile": "",
  "region": "us-east-1",
  "configuration": "Release",
  "function-runtime": "provided.al2023",
  "function-memory-size": 256,
  "function-timeout": 30,
  "function-handler": "bootstrap",
  "msbuild-parameters": "--self-contained true",
  "package-type": "image",
  "docker-host-build-output-dir": "./bin/Release/lambda-publish"
}

  5. Create a Dockerfile in the MyFunction/src/MyFunction directory. The following example Dockerfile uses a Microsoft .NET base image instead of an AWS base image.

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

    • Use the COPY command to copy the function into the /var/task directory.

    • Set the ENTRYPOINT to the module that you want the Docker container to run when it starts. In this case, the module is the bootstrap, which initializes the Amazon.Lambda.RuntimeSupport library.

    Note that the example Dockerfile does not include a USER instruction. When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to the root user when no USER instruction is provided.

    Example Dockerfile
    # You can also pull these images from DockerHub amazon/aws-lambda-dotnet:8
FROM mcr.microsoft.com/dotnet/runtime:8.0

# Set the image's internal work directory
WORKDIR /var/task
  
# Copy function code to Lambda-defined environment variable
COPY "bin/Release/net8.0/linux-x64"  .
  
# Set the entrypoint to the bootstrap
ENTRYPOINT ["/usr/bin/dotnet", "exec", "/var/task/bootstrap.dll"]

  6. Install the Amazon.Lambda.Tools .NET Global Tools extension.

    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

  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 CLI extension, 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

  9. Delete the Lambda function.

    dotnet lambda delete-function MyFunction