This tool can be used to help test .NET Lambda functions for debugging application logic. The .NET Lambda code will run within this tool's process allowing IDEs attached to this tool to step through your .NET Core Lambda code. This tool runs the .NET Lambda code similarly to how the AWS Lambda service runs .NET code but there are intended differences to make debugging simple, for example the host OS. For that reason, this testing tool cannot help with diagnosing platform specific issues.
Since this tool is a .NET Core application that loads the selected .NET code into its process any IDE that can debug .NET Core application can use this tool to debug .NET Lambda code. The easiest way to use this tool is with Visual Studio and the AWS Toolkit for Visual Studio which will automatically configure this tool when a .NET Core Lambda project is opened in Visual Studio. For how to setup this tool for other IDE like Visual Studio for Code or Rider from JetBrains check click here.
.NET Lambda functions can be written as an executable assembly. This is done for Lambda functions using custom runtime or using .NET top level statements. These functions include the Lambda runtime client implemented in the Amazon.Lambda.RuntimeSupport NuGet package. In an executable assembly function the Lambda runtime client is initialized and connects to a local REST endpoint for Lambda events to process.
The Executable Assembly page in this tool hosts a local Lambda runtime API for the Lambda runtime client to connect to. On this page you can queue events for the Lambda function to process.
To test Lambda function built as an executable assembly the environment variable AWS_LAMBDA_RUNTIME_API must be set to @httpContextAccessor.HttpContext.Request.Host. This will tell Amazon.Lambda.RuntimeSupport to connect to this instance of the test tool for Lambda events to process. To configure AWS credentials and region for the function the environment variables AWS_PROFILE and AWS_REGION can be set.
Here is an example of a .NET executable assembly Lambda function's launchSettings.json file used in Visual Studio for debugging that connects to the test tool and sets the profile and region.
{
"profiles": {
"Lambda Runtime API": {
"commandName": "Project",
"environmentVariables": {
"AWS_LAMBDA_RUNTIME_API": "@httpContextAccessor.HttpContext.Request.Host",
"AWS_PROFILE": "test-profile",
"AWS_REGION": "us-west-2"
}
}
}
}
.NET Core uses AssemblyLoadContext objects to load assemblies into a process. Most applications including the .NET Lambda production environment load assemblies in the Default AssemblyLoadContext. This tool loads the provided .NET Lambda code in a separate AssemblyLoadContext to avoid clashes with .NET assemblies used by this tool versus the .NET assemblies used by the provided .NET Lambda code. In some rare cases this difference can affect how the .NET Lambda code runs within this tool compared to the actual Lambda environment.
The web interface part of this tool was developed using Blazor Server Side which uses WebSockets to communicate from the browser to the backend ASP.NET Core process. When you are debugging your Lambda code and are stopped at a breakpoint the ASP.NET Core process isn't responding on the WebSocket. That triggers the Blazor application to signal it isn't currently getting any communication. Once you continue running the application the WebSocket will be reconnected. If the debugger is stopped, killing the test tool process, that will also bring up the message about the application being paused. In this case you can close the browser window.
In the default mode this tool uses the web interface to select the .NET Lambda code to run. It is also possible to skip using the web interface and identify the .NET Lambda code to run using command line arguments. The key command line argument to set is --no-ui which will turn off the web interface. Using the --help command line argument you can see the list of arguments that can be used to identify the .NET Lambda code and set environment settings like aws profile and region as well as a payload JSON document to be used as the function input.
> dotnet lambda-test-tool-3.1 --help
AWS .NET Core 3.1 Mock Lambda Test Tool (0.10.0)
The .NET Lambda Test Tool can be launched in 2 modes. The default mode is to launch a web interface to select the Lambda code
to execute with in the Lambda test tool. The second mode skips using the web interface and the Lambda code is identified
using the commandline switches as described below. To switch to the no web interface mode use the --no-ui command line switch.
These options are valid for either mode the Lambda test tool is running in.
--path <directory> The path to the lambda project to execute. If not set then the current directory will be used.
These options are valid when using the web interface to select and execute the Lambda code.
--host <hostname-or-ip-address> The hostname or IP address used for the test tool's web interface.
Any host other than an explicit IP address or localhost (e.g. '*', '+' or 'example.com')
binds to all public IPv4 and IPv6 addresses.
--port <port-number> The port number used for the test tool's web interface.
--no-launch-window Disable auto launching the test tool's web interface in a browser.
These options are valid in the no web interface mode.
--no-ui Disable launching the web interface and immediately execute the Lambda code.
--profile <profile-name> Set the AWS credentials profile to provide credentials to the Lambda code.
If not set the profile from the config file will be used.
--region <region-name> Set the AWS region to as the default region for the Lambda code being executed.
If not set the region from the config file will be used.
--config-file <file-name> The config file to read for Lambda settings. If not set than aws-lambda-tools-defaults.json
will be used.
--function-handler <handler-string> The Lambda function handler to identify the code to run. If not set then the function handler
from the config file will be used. This is the format of <assembly::type-name::method-name>.
--payload <file-name> The JSON payload to send to the Lambda function. This can be either an inline string or a
file path to a JSON file.
--pause-exit <true or false> If set to true the test tool will pause waiting for a key input before exiting. The is useful
when executing from an IDE so you can avoid having the output window immediately disappear after
executing the Lambda code. The default value is true.
Note: The --host argument do not bind to specific hostname as it's value is largely ignored by web hosting. This is mostly used to expose web interface through docker by binding to all public IP addresses.
For command line arguments not set the defaults and config file will be used to determine the .NET Lambda code to run. For example if you just use the --no-ui argument then the aws-lambda-tools-defaults.json will be searched for and used if found. The tool when then use the function handler, profile and region specified in the configuration file to run .NET Lambda code.
Here is an example of a launchSettings.json file configured to use this tool without the web interface. Only --no-ui and --payload are set turning off the web interface and indicating the contents of the payload.json file should be used as the function input. The function handler is identified from the project's aws-lambda-tools-defaults.json file.
{
"profiles": {
"Mock Lambda Test Tool": {
"commandName": "Executable",
"commandLineArgs": "--no-ui --payload payload.json",
"workingDirectory": ".\\bin\\$(Configuration)\\netcoreapp3.1",
"executablePath": "C:\\Users\\%USERNAME%\\.dotnet\\tools\\dotnet-lambda-test-tool-3.1.exe"
}
}
}
The --payload switch points to a file location of a JSON document that is used as the function input. The file is searched using the following rules.