Improve Lambda Test Tool v2 getting-started docs and add samples

.gitignore

@@ -19,6 +19,8 @@
 **/Deployment/
 **/packages
 **/launchSettings.json
+# Keep the launch profiles for the Lambda Test Tool v2 sample projects (they are part of the docs).
+!Tools/LambdaTestTool-v2/samples/**/launchSettings.json
 **/Debug/
 **/build/
 

Tools/LambdaTestTool-v2/samples/AddFunctionClassLibrary/AddFunctionClassLibrary.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <AWSProjectType>Lambda</AWSProjectType>
+    <AssemblyName>AddFunctionClassLibrary</AssemblyName>
+    <!-- Produces the .deps.json / .runtimeconfig.json the launch profile references. -->
+    <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
+    <!-- Copy NuGet dependencies (Amazon.Lambda.Core, etc.) next to the output DLL so the
+         function can be launched from the command line without extra probing paths. -->
+    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Amazon.Lambda.Core" Version="2.5.0" />
+    <PackageReference Include="Amazon.Lambda.APIGatewayEvents" Version="3.0.0" />
+    <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.4.4" />
+  </ItemGroup>
+
+</Project>

Tools/LambdaTestTool-v2/samples/AddFunctionClassLibrary/Function.cs

@@ -0,0 +1,20 @@
+using Amazon.Lambda.APIGatewayEvents;
+using Amazon.Lambda.Core;
+
+[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.CamelCaseLambdaJsonSerializer))]
+
+namespace AddFunctionClassLibrary;
+
+public class Function
+{
+    /// <summary>
+    /// Adds the two path parameters {x} and {y} and returns the sum.
+    /// Handler string: AddFunctionClassLibrary::AddFunctionClassLibrary.Function::Add
+    /// </summary>
+    public int Add(APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context)
+    {
+        var x = int.Parse(request.PathParameters["x"]);
+        var y = int.Parse(request.PathParameters["y"]);
+        return x + y;
+    }
+}

Tools/LambdaTestTool-v2/samples/AddFunctionClassLibrary/Properties/launchSettings.json

@@ -0,0 +1,13 @@
+{
+  "profiles": {
+    "LambdaTestTool": {
+      "commandName": "Executable",
+      "executablePath": "dotnet",
+      "workingDirectory": ".\\bin\\$(Configuration)\\net8.0",
+      "commandLineArgs": "exec --depsfile ./AddFunctionClassLibrary.deps.json --runtimeconfig ./AddFunctionClassLibrary.runtimeconfig.json %USERPROFILE%/.dotnet/tools/.store/amazon.lambda.testtool/{TEST_TOOL_VERSION}/amazon.lambda.testtool/{TEST_TOOL_VERSION}/content/Amazon.Lambda.RuntimeSupport/net8.0/Amazon.Lambda.RuntimeSupport.TestTool.dll AddFunctionClassLibrary::AddFunctionClassLibrary.Function::Add",
+      "environmentVariables": {
+        "AWS_LAMBDA_RUNTIME_API": "localhost:5050/AddLambdaFunction"
+      }
+    }
+  }
+}

Tools/LambdaTestTool-v2/samples/AddFunctionClassLibrary/README.md

@@ -0,0 +1,78 @@
+# AddFunctionClassLibrary
+
+The same "add two numbers" function as [`AddFunctionTopLevel`](../AddFunctionTopLevel), but as a **class library** (a handler method rather than top-level statements). A class-library function is launched by running its assembly under the test tool's copy of the Lambda runtime support library. You can do this from the command line or from an IDE.
+
+Handler: `AddFunctionClassLibrary::AddFunctionClassLibrary.Function::Add`
+
+## Setup (once)
+
+The `.csproj` sets `<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>` so the function's NuGet dependencies (e.g. `Amazon.Lambda.Core.dll`) are copied next to the output DLL — required for the command-line launch below.
+
+Find your installed test tool version, which you'll substitute for `{TEST_TOOL_VERSION}`:
+
+```
+dotnet lambda-test-tool info
+```
+
+(or `dotnet tool list -g`). For example, `0.15.0`.
+
+> The runtime support assembly is `Amazon.Lambda.RuntimeSupport.TestTool.dll` — renamed from `Amazon.Lambda.RuntimeSupport.dll` to avoid conflicting with the version your function references.
+
+## Run it (command line)
+
+**1. Build the function:**
+
+```
+dotnet build
+```
+
+**2. Set the API Gateway route** (this directory):
+
+```bash
+# Linux/macOS
+export APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"http://localhost:5050"}'
+```
+
+```powershell
+# Windows (PowerShell)
+$env:APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"http://localhost:5050"}'
+```
+
+**3. Start the test tool** (same terminal):
+
+```
+dotnet lambda-test-tool start --lambda-emulator-port 5050 --api-gateway-emulator-port 5051 --api-gateway-emulator-mode HttpV2
+```
+
+**4. Start the function** from its build output directory (separate terminal), replacing `{TEST_TOOL_VERSION}` with your installed version:
+
+```bash
+# Linux/macOS
+cd bin/Debug/net8.0
+export AWS_LAMBDA_RUNTIME_API="localhost:5050/AddLambdaFunction"
+
+dotnet exec \
+    --depsfile ./AddFunctionClassLibrary.deps.json \
+    --runtimeconfig ./AddFunctionClassLibrary.runtimeconfig.json \
+    "$HOME/.dotnet/tools/.store/amazon.lambda.testtool/{TEST_TOOL_VERSION}/amazon.lambda.testtool/{TEST_TOOL_VERSION}/content/Amazon.Lambda.RuntimeSupport/net8.0/Amazon.Lambda.RuntimeSupport.TestTool.dll" \
+    "AddFunctionClassLibrary::AddFunctionClassLibrary.Function::Add"
+```
+
+**5. Invoke it:**
+
+```
+curl "http://localhost:5051/add/5/3"
+# => 8
+```
+
+## Run it (IDE: Visual Studio / Rider)
+
+The committed [`launchSettings.json`](Properties/launchSettings.json) wraps the same command as an `Executable` profile you can launch with F5. Before using it, replace `{TEST_TOOL_VERSION}` (it appears **twice** in the `commandLineArgs` `.store` path) with your installed version.
+
+The other values are already set for this project: target framework `net8.0`, deps/runtimeconfig file names, and the handler string.
+
+> This profile relies on the IDE expanding `$(Configuration)` and resolving `workingDirectory`. Plain `dotnet run --launch-profile` does **not** do this — use the command-line steps above outside an IDE.
+
+> The profile is written for **Windows** (`%USERPROFILE%`, backslashes). On **Linux/macOS**, replace `%USERPROFILE%` with `$HOME` and use forward slashes in `workingDirectory` (`./bin/$(Configuration)/net8.0`).
+
+Then set `APIGATEWAY_EMULATOR_ROUTE_CONFIG`, start the test tool (steps 2–3 above), press F5 on the `LambdaTestTool` profile, and invoke with the step 5 curl.

Tools/LambdaTestTool-v2/samples/AddFunctionTopLevel/AddFunctionTopLevel.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <AWSProjectType>Lambda</AWSProjectType>
+    <AssemblyName>AddFunctionTopLevel</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Amazon.Lambda.Core" Version="2.5.1" />
+    <PackageReference Include="Amazon.Lambda.APIGatewayEvents" Version="3.0.0" />
+    <PackageReference Include="Amazon.Lambda.RuntimeSupport" Version="1.13.0" />
+    <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.4.4" />
+  </ItemGroup>
+
+</Project>

Tools/LambdaTestTool-v2/samples/AddFunctionTopLevel/Program.cs

@@ -0,0 +1,17 @@
+using Amazon.Lambda.APIGatewayEvents;
+using Amazon.Lambda.Core;
+using Amazon.Lambda.RuntimeSupport;
+using Amazon.Lambda.Serialization.SystemTextJson;
+
+// Adds the two path parameters {x} and {y} and returns the sum.
+// Uses the HTTP API v2 request shape, so run the API Gateway emulator in HttpV2 mode.
+var handler = (APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context) =>
+{
+    var x = int.Parse(request.PathParameters["x"]);
+    var y = int.Parse(request.PathParameters["y"]);
+    return (x + y).ToString();
+};
+
+await LambdaBootstrapBuilder.Create(handler, new CamelCaseLambdaJsonSerializer())
+    .Build()
+    .RunAsync();

Tools/LambdaTestTool-v2/samples/AddFunctionTopLevel/Properties/launchSettings.json

@@ -0,0 +1,10 @@
+{
+  "profiles": {
+    "AddLambdaFunction": {
+      "commandName": "Project",
+      "environmentVariables": {
+        "AWS_LAMBDA_RUNTIME_API": "localhost:5050/AddLambdaFunction"
+      }
+    }
+  }
+}

Tools/LambdaTestTool-v2/samples/AddFunctionTopLevel/README.md

@@ -0,0 +1,38 @@
+# AddFunctionTopLevel
+
+The [Quick Start](../../README.md#quick-start) function: a top-level-statements Lambda that adds two numbers, invoked through the API Gateway emulator. Uses the HTTP API v2 request shape, so the API Gateway emulator runs in `HttpV2` mode.
+
+## Run it
+
+**1. In this directory, set the API Gateway route** the emulator should expose:
+
+```bash
+# Linux/macOS
+export APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"http://localhost:5050"}'
+```
+
+```powershell
+# Windows (PowerShell)
+$env:APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"http://localhost:5050"}'
+```
+
+**2. Start the test tool** (same terminal):
+
+```
+dotnet lambda-test-tool start --lambda-emulator-port 5050 --api-gateway-emulator-port 5051 --api-gateway-emulator-mode HttpV2
+```
+
+**3. Start the function** (separate terminal, this directory):
+
+```
+dotnet run --launch-profile AddLambdaFunction
+```
+
+**4. Invoke it:**
+
+```
+curl "http://localhost:5051/add/5/3"
+# => 8
+```
+
+You can also invoke the function directly (without API Gateway) from the web UI that opens at `http://localhost:5050`.

Tools/LambdaTestTool-v2/samples/README.md

@@ -0,0 +1,17 @@
+# Lambda Test Tool v2 — Sample Projects
+
+Runnable starter functions for the [AWS Lambda Test Tool](../README.md). Each is a minimal, self-contained project with its own README and a ready-to-use launch profile.
+
+| Sample | What it shows | Emulator setup |
+|--------|---------------|----------------|
+| [`AddFunctionTopLevel`](AddFunctionTopLevel) | Top-level-statements function behind the API Gateway emulator (the [Quick Start](../README.md#quick-start)). | Lambda + API Gateway (`HttpV2`) |
+| [`AddFunctionClassLibrary`](AddFunctionClassLibrary) | A class-library function with a pre-filled `Executable` launch profile. | Lambda + API Gateway (`HttpV2`) |
+| [`SQSProcessor`](SQSProcessor) | An `SQSEvent` handler, testable via the SQS event source or the built-in `sqs.json` sample event. | Lambda (+ optional SQS event source) |
+| [`ToUpperFunction`](ToUpperFunction) | A minimal, zero-dependency function for exploring the web UI and sample events. | Lambda only |
+
+## Prerequisites
+
+- .NET 8 SDK or later.
+- The test tool installed: `dotnet tool install -g amazon.lambda.testtool` (see the [main README](../README.md#prerequisites)).
+
+Start with [`AddFunctionTopLevel`](AddFunctionTopLevel) if you're new — it's the lowest-friction path from install to a working invocation.

Tools/LambdaTestTool-v2/samples/SQSProcessor/Program.cs

@@ -0,0 +1,21 @@
+using Amazon.Lambda.Core;
+using Amazon.Lambda.RuntimeSupport;
+using Amazon.Lambda.Serialization.SystemTextJson;
+using Amazon.Lambda.SQSEvents;
+
+// Processes a batch of SQS messages, logging each message body.
+// Test it either with the built-in "sqs.json" sample event from the web UI,
+// or by wiring a real queue with --sqs-eventsource-config (see this sample's README).
+var handler = (SQSEvent evnt, ILambdaContext context) =>
+{
+    foreach (var message in evnt.Records)
+    {
+        context.Logger.LogLine($"Processing message {message.MessageId}: {message.Body}");
+    }
+
+    context.Logger.LogLine($"Processed {evnt.Records.Count} message(s).");
+};
+
+await LambdaBootstrapBuilder.Create(handler, new DefaultLambdaJsonSerializer())
+    .Build()
+    .RunAsync();

Tools/LambdaTestTool-v2/samples/SQSProcessor/Properties/launchSettings.json

@@ -0,0 +1,10 @@
+{
+  "profiles": {
+    "SQSProcessor": {
+      "commandName": "Project",
+      "environmentVariables": {
+        "AWS_LAMBDA_RUNTIME_API": "localhost:5050/SQSProcessor"
+      }
+    }
+  }
+}

Tools/LambdaTestTool-v2/samples/SQSProcessor/README.md

@@ -0,0 +1,39 @@
+# SQSProcessor
+
+An `SQSEvent` handler that logs each message body. Demonstrates the shape of an SQS-triggered Lambda and the [SQS event source](../../README.md#sqs-event-source). You can test it two ways.
+
+## Option A: With the built-in sample event (no AWS needed)
+
+**1. Start the Lambda emulator:**
+
+```
+dotnet lambda-test-tool start --lambda-emulator-port 5050
+```
+
+**2. Start the function** (separate terminal, this directory):
+
+```
+dotnet run --launch-profile SQSProcessor
+```
+
+**3. In the web UI** (`http://localhost:5050`), select `SQSProcessor`, choose the built-in **`sqs.json`** sample from the Example Requests dropdown, and click **Invoke**. The message body is logged in the function's console.
+
+## Option B: With a real SQS queue (event source polling)
+
+This polls an actual queue using your AWS credentials.
+
+**1. Start the function** (separate terminal, this directory):
+
+```
+dotnet run --launch-profile SQSProcessor
+```
+
+**2. Start the test tool with the SQS event source** pointed at your queue:
+
+```
+dotnet lambda-test-tool start \
+    --lambda-emulator-port 5050 \
+    --sqs-eventsource-config "QueueUrl=https://sqs.<region>.amazonaws.com/<account-id>/<queue-name>,FunctionName=SQSProcessor,Region=<region>"
+```
+
+Send a message to the queue; the tool batches it into an `SQSEvent`, invokes `SQSProcessor`, and (on success) deletes the message. See the [main README](../../README.md#sqs-event-source) for all supported config keys.

Tools/LambdaTestTool-v2/samples/SQSProcessor/SQSProcessor.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <AWSProjectType>Lambda</AWSProjectType>
+    <AssemblyName>SQSProcessor</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Amazon.Lambda.Core" Version="2.5.1" />
+    <PackageReference Include="Amazon.Lambda.SQSEvents" Version="3.0.0" />
+    <PackageReference Include="Amazon.Lambda.RuntimeSupport" Version="1.13.0" />
+    <PackageReference Include="Amazon.Lambda.Serialization.SystemTextJson" Version="2.4.4" />
+  </ItemGroup>
+
+</Project>

Tools/LambdaTestTool-v2/samples/ToUpperFunction/Program.cs

@@ -0,0 +1,21 @@
+using Amazon.Lambda.Core;
+using Amazon.Lambda.RuntimeSupport;
+using Amazon.Lambda.Serialization.SystemTextJson;
+
+// A minimal function: uppercases the input string.
+// Send the string "error" to see how the tool renders a thrown exception.
+var handler = (string input, ILambdaContext context) =>
+{
+    context.Logger.LogLine($"Executing function with input: {input}");
+
+    if (string.Equals("error", input, StringComparison.OrdinalIgnoreCase))
+    {
+        throw new Exception("Forced error to demonstrate error rendering.");
+    }
+
+    return input?.ToUpper();
+};
+
+await LambdaBootstrapBuilder.Create(handler, new DefaultLambdaJsonSerializer())
+    .Build()
+    .RunAsync();

Tools/LambdaTestTool-v2/samples/ToUpperFunction/Properties/launchSettings.json

@@ -0,0 +1,10 @@
+{
+  "profiles": {
+    "ToUpperFunction": {
+      "commandName": "Project",
+      "environmentVariables": {
+        "AWS_LAMBDA_RUNTIME_API": "localhost:5050/ToUpperFunction"
+      }
+    }
+  }
+}