Overview
Ever want to run your AWS lambda functions locally so you can debug efficiently? Well, the documentation for doing so isn’t in one nice, convenient location. Still, the tools ARE THERE. You just need instructions on what to set up and how. That’s what this article will attempt to help you accomplish.
Assumptions
I’m assuming a Windows and Visual Studio environment here. If that’s not your go-to, I’m imagining the adjustments are small. If you’d like to share your adjustments, I’m happy to update this article.
I’m also assuming you started your project with the AWS Lambda Project (.NET Core, C#) template.
Pre-requisites
Before you can debug, the following must be installed:
- Visual Studio 2022 or higher – look at the date this article was written
- AWS CLI 2 or higher
- AWS Toolkit Visual Studio Plug-in
- AWS Lambda Mock Test Tool – install the version appropriate for your project’s .NET target, such as -8.0 for .NET 8
- Java 1.7 or higher Runtime, if debugging DynamoDb locally, otherwise no need
Lambda Mock Test Tool Install Shortcut
You can install the Mock Test Tool from the command line easily. Just open PowerShell and run the following command:
dotnet tool install -g Amazon.Lambda.TestTool-8.0
Note the -8.0 needs to match the .NET version. Here are some versions to choose from, which will update from time to time. See the Github repo in Pre-requisites for the latest table.
| .NET Core Version | Tool NuGet Package | Tool executable |
|---|---|---|
| .NET Core 2.1 (Deprecated) | Amazon.Lambda.TestTool-2.1 | dotnet-lambda-test-tool-2.1.exe |
| .NET Core 3.1 (Deprecated) | Amazon.Lambda.TestTool-3.1 | dotnet-lambda-test-tool-3.1.exe |
| .NET 5.0 (Deprecated) | Amazon.Lambda.TestTool-5.0 | dotnet-lambda-test-tool-5.0.exe |
| .NET 6.0 | Amazon.Lambda.TestTool-6.0 | dotnet-lambda-test-tool-6.0.exe |
| .NET 7.0 (Deprecated) | Amazon.Lambda.TestTool-7.0 | dotnet-lambda-test-tool-7.0.exe |
| .NET 8.0 | Amazon.Lambda.TestTool-8.0 | dotnet-lambda-test-tool-8.0.exe |
| .NET 9.0 | Amazon.Lambda.TestTool-9.0 | dotnet-lambda-test-tool-9.0.exe |
Configuring Your Project
In your project, you will need to make some adjustments in order to debug.
Update launchSettings.json
In the project’s launchSettings.json file, make sure you are pointing to the Mock Lamda Test Tool profile and environmentVariables are specified. Something like this:
{
"profiles": {
"Mock Lambda Test Tool": {
"commandName": "Executable",
"commandLineArgs": "--port 5050",
"workingDirectory": ".\\bin\\$(Configuration)\\net8.0",
"executablePath": "%USERPROFILE%\\.dotnet\\tools\\dotnet-lambda-test-tool-8.0.exe",
"environmentVariables": {
"AWS_LAMBDA_RUNTIME_API": "localhost:5050",
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-2",
"DYNAMODB_ENDPOINT": "http://localhost:8000"
}
}
}
}
The DYNAMODB_ENDPOINT is optional, and your tastes for naming environment variables may vary.
Make sure the workingDirectory and executablePath are set to the appropriate version of your installed .NET and Lambda Mock Test Tool versions.
Update aws-lambda-tools-defaults.json
You must also tell the Lambda Mock Test Tool where to find the function to point your requests. You can only test one function at a time (sorry), but it’s easy to update.
Populate the function-handler setting in the aws-lambda-tools-defaults.json file as follows:
{
"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": "default",
"region": "us-east-1",
"configuration": "Release",
"function-architecture": "arm64",
"function-runtime": "dotnet8",
"function-memory-size": 128,
"function-timeout": 30,
"function-handler": "assemblyName::fullClassPath::nameOfFunction",
"framework": "net8.0",
"package-type": "Zip"
}
See it there, on line 15? Populate it as follows:
- assemblyName: The name of your assembly. For example, OhMyLambda.
- fullClassPath: The full path of the class containing your function. For example, OhMyLambda.MyFunctionClass
- nameOfFunction: The name of your function, such as Handler
So, if you had a class like this:
// 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 OhMyLambda.Functions;
public class MyFunctionClass(IAmazonDynamoDB dynamoDbClient)
{
public MyFunctionClass() : this(CreateDynamoDbClient()) { }
public async Task<APIGatewayProxyResponse> Handler(APIGatewayProxyRequest request, ILambdaContext context)
{
... more code here ...
…then your function-handler line would look like:
"function-handler": "OhMyLambda::OhMyLambda.Functions.MyFunctionClass::Handler",
All good? Let’s continue.
Before You Debug
Before debugging, make sure you see Mock Lambda Test Tool as your startup option. You should also have DynamoDb running if it’s needed.
Starting DynamoDb
If you also need DynamoDb to be running, you should start it before debugging. If you have installed DynamoDb Local from the link above, you need to get AWS Credentials and THEN start it.
To get AWS credentials for the local instance, open PowerShell and run aws configure and use the following credentials:
- AWS Access Key ID [None]: fakeMyKeyId
- AWS Secret Access Key [None]: fakeSecretAccessKey
- Default Region Name [None]: fakeRegion
- Default output format [None]: (just hit enter)
This will take care of being able to access DynamoDb locally with the proper credentials
Once the credentials have been set, you can launch DynamoDb as follows:
java -D”java.library.path=./DynamoDBLocal_lib” -jar DynamoDBLocal.jar -sharedDb
I added this to a batch file to quickly run it from File Explorer.
This will launch DynamoDb. You can press Control-C to end its process when you’re done.
Debugging
You should be all set now. Simply launch the debugger and you should see the Mock Lambda Test Tool appear in your default web browser. It will look something like this:
If you don’t see your function details, or the top two dropdowns are empty, you have an error in your configuration. Make sure that function-handler is correct!
Triggering the Lambda
So how do you send the payload and trigger the Lambda? Amazon has you covered – just select API Gateway AWS Proxy from the Example Requests dropdown. Then, fill in the “body” with the proper JSON-formatted-as-string. Hit Execute Function, and the request will be made and should trigger your debug breakpoint, assuming you’ve set one.
The End
That’s it! You should be able to debug now! I hope this helped. If you have any updates or questions, feel free to hit me up. You can find me on LinkedIn: https://www.linkedin.com/in/aurirahimzadeh
Auri's Blog 