.NET Core CLI
The .NET Core CLI offers a cross-platform way for you to create .NET-based Lambda applications. This section
assumes that you have installed the .NET Core CLI. If you haven't, see Download .NET
In the .NET CLI, you use the new
command to create .NET projects from a command line. This is
useful if you want to create a project outside of Visual Studio. To view a list of the available project types,
open a command line, navigate to where you installed the .NET Core runtime, and then run the following
command:
dotnet new list Usage: new [options] ... Templates Short Name Language Tags ---------------------------------------------------------------------------------------------------------------------------- Console Application console [C#], F#, VB Common/Console Class library classlib [C#], F#, VB Common/Library Unit Test Project mstest [C#], F#, VB Test/MSTest xUnit Test Project xunit [C#], F#, VB Test/xUnit ... Examples: dotnet new mvc --auth Individual dotnet new viewstart dotnet new --help
Lambda offers additional templates via the Amazon.Lambda.Templates
dotnet new -i Amazon.Lambda.Templates
Once the install is complete, the Lambda templates show up as part of dotnet new
. To examine
details about a template, use the help
option.
dotnet new lambda.EmptyFunction --help
The lambda.EmptyFunction
template supports the following options:
-
--name
– The name of the function -
--profile
– The name of a profile in your Amazon SDK for .NET credentials file -
--region
– The Amazon Region to create the function in
These options are saved to a file named aws-lambda-tools-defaults.json
.
Create a function project with the lambda.EmptyFunction
template.
dotnet new lambda.EmptyFunction --name MyFunction
Under the src/myfunction
directory, examine the following files:
-
aws-lambda-tools-defaults.json: This is where you specify the command line options when deploying your Lambda function. For example:
"profile" : "default", "region" : "us-east-2", "configuration" : "Release", "function-runtime":"dotnet6", "function-memory-size" : 256, "function-timeout" : 30, "function-handler" : "MyFunction::MyFunction.Function::FunctionHandler"
-
Function.cs: Your Lambda handler function code. It's a C# template that includes the default
Amazon.Lambda.Core
library and a defaultLambdaSerializer
attribute. For more information on serialization requirements and options, see Serializing Lambda functions. It also includes a sample function that you can edit to apply your Lambda function code.using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Amazon.Lambda.Core; // Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class. [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))] namespace MyFunction { public class Function { public string FunctionHandler(string input, ILambdaContext context) { return input.ToUpper(); } } }
-
MyFunction.csproj: An MSBuild
file that lists the files and assemblies that comprise your application. <Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <TargetFramework>net6.0</TargetFramework> <ImplicitUsings>enable</ImplicitUsings> <Nullable>enable</Nullable> <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles> <AWSProjectType>Lambda</AWSProjectType> <!-- Makes the build directory similar to a publish directory and helps the Amazon .NET Lambda Mock Test Tool find project dependencies. --> <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> <!-- Generate ready to run images during publishing to improve cold start time. --> <PublishReadyToRun>true</PublishReadyToRun> </PropertyGroup> <ItemGroup> <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0 " /> <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.2.0" /> </ItemGroup> </Project>
-
Readme: Use this file to document your Lambda function.
Under the myfunction/test
directory, examine the following files:
-
myFunction.Tests.csproj: As noted previously, this is an MSBuild
file that lists the files and assemblies that comprise your test project. Note also that it includes the Amazon.Lambda.Core
library, so you can seamlessly integrate any Lambda templates required to test your function.<Project Sdk="Microsoft.NET.Sdk"> ... <PackageReference Include="Amazon.Lambda.Core" Version="2.1.0 " /> ...
-
FunctionTest.cs: The same C# code template file that it is included in the
src
directory. Edit this file to mirror your function's production code and test it before uploading your Lambda function to a production environment.using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Xunit; using Amazon.Lambda.Core; using Amazon.Lambda.TestUtilities; using MyFunction; namespace MyFunction.Tests { public class FunctionTest { [Fact] public void TestToUpperFunction() { // Invoke the lambda function and confirm the string was upper cased. var function = new Function(); var context = new TestLambdaContext(); var upperCase = function.FunctionHandler("hello world", context); Assert.Equal("HELLO WORLD", upperCase); } } }
Once your function has passed its tests, you can build and deploy using the Amazon.Lambda.Tools .NET Core Global Tool
dotnet tool install -g Amazon.Lambda.Tools
If you already have the tool installed, you can make sure that it is the latest version using the following command:
dotnet tool update -g Amazon.Lambda.Tools
For more information about the Amazon.Lambda.Tools .NET Core Global Tool, see the Amazon Extensions for .NET CLI
With the Amazon.Lambda.Tools installed, you can deploy your function using the following command:
dotnet lambda deploy-function MyFunction --function-role role
After deployment, you can re-test it in a production environment using the following command, and pass in a different value to your Lambda function handler:
dotnet lambda invoke-function MyFunction --payload "Just Checking If Everything is OK"
If everything is successful, you see the following:
dotnet lambda invoke-function MyFunction --payload "Just Checking If Everything is OK" Payload: "JUST CHECKING IF EVERYTHING IS OK" 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
Using Lambda layers with the .NET CLI
Note
Using layers with functions in a compiled language like C# may not provide the same amount of benefit as with an interpreted language like Python. Since C# is a compiled language, your functions still have to manually load any shared assemblies into memory during the init phase, which can increase cold start times. Instead, we recommend including any shared code at compile time to take advantage of any built-in compiler optimizations.
The .NET CLI supports commands to help you publish layers and deploy C# functions that
consume layers. To publish a layer to a specified Amazon S3 bucket, run the following command
in the same directory as your .csproj
file:
dotnet lambda publish-layer
<layer_name>
--layer-type runtime-package-store --s3-bucket<s3_bucket_name>
Then, when you deploy your function using the .NET CLI, specify the layer ARN the consume in the following command:
dotnet lambda deploy-function
<function_name>
--function-layersarn:aws:lambda:us-east-1:123456789012:layer:layer-name:1
For a complete example of a Hello World function, see the
blank-csharp-with-layer