Skip to main content

Start a new project

It's possible to run a traditional ASP.NET on AWS Lambda without changing a single line of code in your existing application. By traditional, I mean an API that was around before Microsoft got rid of the Startup.cs file in new projects created from .NET 6 onwards. If you have an existing API that still has a Startup.cs file, read on. If you have an API that uses a single Program.cs file with all the startup logic, check out the documentation on minimal API's on Lambda.

To demonstrate how to run do this, let's start with a brand new project. Yes, I know .NET Core 3.1 is out of support! This is the only way to generate a new project that still includes a Startup.cs file.

new-project
dotnet new webapi -f netcoreapp3.1 -n WebApi.OnLambda

Once initialised, open the project in the IDE of your choice. The sample API contains a single controller with a single GET /weatherforecast endpoint. Remember, we are going to run this application on Lambda without changing a single line of existing application code.

.NET 6

The first thing to do is bump the TargetFramework to be net6.0. You can do that in the WebApi.OnLambda.csproj file.

Nuget Package

The next step to enable Lambda support is to install the Amazon.Lambda.AspNetCoreServer Nuget package. This package provides classes and functionality to proxy the event payload passed to Lambda into a format that ASP.NET can understand

New Class

The third step is to create a new class in your project. This class is the entry point that Lambda will use when invoking your function. The name of the class is irrelevant, but I'd probably recommend calling it something sensible like LambdaEntryPoint.cs. This class needs to inherit from one of either APIGatewayHttpApiV2ProxyFunction, APIGatewayProxyFunction or ApplicationLoadBalancerFunction. Choose the correct base class depending on what you are putting in front of Lambda.

Configure Startup

You'll also need to override the Init method to configure the correct Startup class. You could also use this override to perform any Lambda specific startup logic that you may not want to do when running outside of Lambda. There are more details on this configuration in the Amazon.Lambda.Tools GitHub repo.

Add deployment configuration

Finally, add a new JSON file to your project named aws-lambda-tools-defaults.json. For more information on the contents of this file, checkout the Deployment Configuration tutorial. The most important setting in here is the FunctionHandler. The handler will always be in the format ASSEMBLYNAME::NAMESPACE.CLASS_NAME_FROM_PREVIOUS_STEP::FunctionHandlerAsync. All of the inherited base classes contain a method named FunctionHandlerAsync, this is what the Lambda service needs to invoke.

project-file
ExpandClose
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
</PropertyGroup>
</Project>

And that's it, that is all you need to do to enable your existing ASP.NET API to be hosted on AWS Lambda. To deploy this to AWS Lambda, you can follow the instructions in the deploy tutorial.

Use the below JSON payload to test your Lambda function, either in the AWS Console or using the dotnet lambda invoke-function CLI Command.

{
"version": "2.0",
"routeKey": "$default",
"rawPath": "/weatherforecast",
"requestContext": {
"http": {
"method": "GET",
"path": "/weatherforecast"
}
},
"isBase64Encoded": false
}