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>net10.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.1" />
+    <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)\\net10.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/net10.0/Amazon.Lambda.RuntimeSupport.TestTool.dll AddFunctionClassLibrary::AddFunctionClassLibrary.Function::Add",
+      "environmentVariables": {
+        "AWS_LAMBDA_RUNTIME_API": "localhost:5050/AddLambdaFunction"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.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/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 10 SDK (the samples target `net10.0`). To build them with an older SDK, change `<TargetFramework>` to `net8.0` or `net9.0`.
+- 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/SQSProcessor.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.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"
+      }
+    }
+  }
+}

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

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