Update README.md for .NET Core Lambda Test Tool

normj · normj · commit 23b325238819 · 2020-03-27T16:16:35.000-07:00
diff --git a/Tools/LambdaTestTool/README.md b/Tools/LambdaTestTool/README.md
@@ -14,41 +14,113 @@ The AWS .NET Mock Lambda Test Tool is a tool that can be used to load a .NET Cor
 - [Configure for Visual Studio for Mac](#configure-for-visual-studio-for-mac)
 - [Known Limitations](#known-limitations)
 
-## Getting Help
+## Getting help
 
 This tool is currently in preview and there are some known limitations. For questions and problems please open a GitHub issue in this repository.
 
+## Versions of the tool
+
+There are separate versions of this tool for each support .NET Core Lambda runtime. Currently there are too supported versions .NET Core 2.1
+and .NET Core 3.1. When using the AWS [AWS Toolkit for Visual Studio](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.AWSToolkitforVisualStudio2017)
+
+
+|.NET Core Version | Tool NuGet Package | Tool executable|
+|------------------|--------------------|----------------|
+| .NET Core 2.1 | Amazon.Lambda.TestTool-2.1 | dotnet-lambda-test-tool-2.1.exe |
+| .NET Core 3.1 | Amazon.Lambda.TestTool-3.1 | dotnet-lambda-test-tool-3.1.exe |
+
 ## AWS Credentials
 
-In the Lambda environment an IAM Role is assigned to the function that delivers AWS Credentials to the Lambda compute environment. When service clients from the AWS SDK for .NET are created without explicit credentials the SDK will search the running environment for credentials and find the credentials delivered by the IAM role.
+In the Lambda environment an IAM Role is assigned to the function that delivers AWS Credentials to the Lambda compute environment. When 
+service clients from the AWS SDK for .NET are created without explicit credentials the SDK will search the running environment for 
+credentials and find the credentials delivered by the IAM role.
 
-IAM Roles are **not** used with this tool. Instead a credential profile is selected from the host machine's credential before the code is run. The **AWS_PROFILE** environment variable is set to the selected profile. Just like in the Lambda environment when a service client is created without explicit credentials the SDK searches for credentials and will find the AWS_PROFILE environment variable and retrieve the credentials from the local credential file.
+IAM Roles are **not** used with this tool. Instead a credential profile is selected from the host machine's credential before the code is 
+run. The **AWS_PROFILE** environment variable is set to the selected profile. Just like in the Lambda environment when a service client 
+is created without explicit credentials the SDK searches for credentials and will find the AWS_PROFILE environment variable and retrieve the 
+credentials from the local credential file.
 
-## Installing and Running
+## Installing and running
 
-The tool is distributed as a .NET Global Tool via the NuGet package Amazon.Lambda.TestTool-2.1. To install the tool execute the following command:
+The tool is distributed as .NET Global Tools via the NuGet packages. There is a package for each Lambda runtime supported which the table above describes. 
+The suffix of each package indicates the version of .NET Core the package is for. To install the tool execute the following command:
 
 ```
-dotnet tool install -g Amazon.Lambda.TestTool-2.1
+dotnet tool install -g Amazon.Lambda.TestTool-3.1
 ```
 
 To update the tool run the following command:
 
 ```
-dotnet tool update -g Amazon.Lambda.TestTool-2.1
+dotnet tool update -g Amazon.Lambda.TestTool-3.1
 ```
 
 The main intention for this tool is to make it easy to debug .NET Core Lambda code from an IDE. The tool can be run without an IDE by executing the following command from the project directory. The .NET Core Lambda project **must be built for debug** before running this tool. It doesn't do this automatically because it is assumed an IDE will have built the project before executing this program.
 
 ```
-dotnet lambda-test-tool-2.1
+dotnet lambda-test-tool-3.1
 ```
 
+## Skip using the web interface
+
+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 <b>--no-ui</b> which will turn off the web interface. Using the <b>--help</b> 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.
+
+<pre style="white-space: pre-wrap; background-color:lightgray;font-size:85%">
+&gt; 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 &lt;directory&gt;                    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.
 
-### Why the 2.1 Suffix?
+        --port &lt;port-number&gt;                  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.
 
-Since this tool loads .NET Core Lambda code within its process the version of .NET Core must match the target Lambda Runtime, which is .NET Core 2.1 in this case. When future .NET Core Lambda environments become available a new NuGet package will be released with the suffix updated to match the target framework.
+These options are valid in the no web interface mode.
 
+        --no-ui                               Disable launching the web interface and immediately execute the Lambda code.
+        --profile &lt;profile-name&gt;              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 &lt;region-name&gt;                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 &lt;file-name&gt;             The config file to read for Lambda settings. If not set than aws-lambda-tools-defaults.json
+                                              will be used.
+        --function-handler &lt;handler-string&gt;   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 &lt;assembly::type-name::method-name&gt;.
+        --payload &lt;file-name&gt;                 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 &lt;true or false&gt;          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.
+</pre>
+
+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 <b>--no-ui</b> argument then the
+<b>aws-lambda-tools-defaults.json</b> 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 <b>launchSettings.json</b> file configured to use this tool without the web interface. Only <b>--no-ui</b> and <b>--payload</b> 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 <b>aws-lambda-tools-defaults.json</b> file.
+
+<pre style="white-space: pre-wrap; background-color:lightgray;font-size:85%">
+{
+  "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"
+    }
+  }
+}
+</pre>
 
 ## Configure for Visual Studio
 
@@ -61,8 +133,8 @@ When a project is opened in Visual Studio the toolkit will detect the project is
     "Mock Lambda Test Tool": {
       "commandName": "Executable",
       "commandLineArgs": "--port 5050",
-      "executablePath": "<home-directory>\\.dotnet\\tools\\dotnet-lambda-test-tool-2.1.exe",
-      "workingDirectory": ".\\bin\\Debug\\netcoreapp2.1"
+      "executablePath": "<home-directory>\\.dotnet\\tools\\dotnet-lambda-test-tool-3.1.exe",
+      "workingDirectory": ".\\bin\\Debug\\netcoreapp3.1"
     }
   }
 }
@@ -73,7 +145,7 @@ When a project is opened in Visual Studio the toolkit will detect the project is
 
 Before using Visual Studio Code you must follow the instructions above on installing the .NET Mock Lambda Test Tool.
 
-To debug with Visual Studio Code and the .NET Mock Lambda Test Tool edit the [launch.json](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) configuration file and have the `program` property point to `dotnet-lambda-test-tool-2.1.exe` and make sure `cwd` is pointing the .NET Core Lambda project. Note that on a non-windows environment the executable will be called `dotnet-lambda-test-tool-2.1` without the ".exe" at the end. The `dotnet-lambda-test-tool-2.1.exe` executable can be found in the `.dotnet/tools` directory under your home directory. Depending on your file system settings, the `.dotnet` directory can appear hidden.
+To debug with Visual Studio Code and the .NET Mock Lambda Test Tool edit the [launch.json](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) configuration file and have the `program` property point to `dotnet-lambda-test-tool-.1.exe` and make sure `cwd` is pointing the .NET Core Lambda project. Note that on a non-windows environment the executable will be called `dotnet-lambda-test-tool-3.1` without the ".exe" at the end. The `dotnet-lambda-test-tool-3.1.exe` executable can be found in the `.dotnet/tools` directory under your home directory. Depending on your file system settings, the `.dotnet` directory can appear hidden.
 
 ```json
 {
@@ -84,7 +156,7 @@ To debug with Visual Studio Code and the .NET Mock Lambda Test Tool edit the [la
             "type": "coreclr",
             "request": "launch",
             "preLaunchTask": "build",
-            "program": "<home-directory>/.dotnet/tools/dotnet-lambda-test-tool-2.1.exe",
+            "program": "<home-directory>/.dotnet/tools/dotnet-lambda-test-tool-3.1.exe",
             "args": [],
             "cwd": "${workspaceFolder}",
             "console": "internalConsole",
@@ -105,10 +177,10 @@ To customize the launch behavior for the debugger, you can pass additional argum
 
 Before using JetBrains Rider you must follow the instructions above on installing the .NET Mock Lambda Test Tool.
 
-Configuring  Rider to use the .NET Mock Lambda Test Tool is a little different compared to Visual Studio. For Rider the executable target needs to be the main assembly `Amazon.Lambda.TestTool.dll` for the Test Tool and **not** the Global Tool executable `dotnet-lambda-test-tool-2.1`. The path to `Amazon.Lambda.TestTool.dll` is:
+Configuring  Rider to use the .NET Mock Lambda Test Tool is a little different compared to Visual Studio. For Rider the executable target needs to be the main assembly `Amazon.Lambda.TestTool.dll` for the Test Tool and **not** the Global Tool executable `dotnet-lambda-test-tool-3.1`. The path to `Amazon.Lambda.TestTool.dll` is:
 
 ```
-<home-directory>/.dotnet/tools/.store/amazon.lambda.testtool-2.1/<nuget-version>/amazon.lambda.testtool-2.1/<nuget-version>/tools/netcoreapp2.1/any/Amazon.Lambda.TestTool.dll
+<home-directory>/.dotnet/tools/.store/amazon.lambda.testtool-3.1/<nuget-version>/amazon.lambda.testtool-3.1/<nuget-version>/tools/netcoreapp3.1/any/Amazon.Lambda.TestTool.dll
 ```
 
 Remember when you update your version of the .NET Mock Lambda Test Tool to update the nuget versions numbers in this path string for your IDE's configuration.
@@ -128,10 +200,10 @@ After following these steps, any time you start the debugger in Rider, it will s
 
 Before using Visual Studio for Mac you must follow the instructions above on installing the .NET Mock Lambda Test Tool.
 
-Configuring Visual Studio for Mac to use the .NET Mock Lambda Test Tool is a little different compared to Visual Studio. For Visual Studio for Mac the executable target needs to be the main assembly `Amazon.Lambda.TestTool.dll` for the Test Tool and **not** the Global Tool executable `dotnet-lambda-test-tool-2.1`. The path to `Amazon.Lambda.TestTool.dll` is:
+Configuring Visual Studio for Mac to use the .NET Mock Lambda Test Tool is a little different compared to Visual Studio. For Visual Studio for Mac the executable target needs to be the main assembly `Amazon.Lambda.TestTool.dll` for the Test Tool and **not** the Global Tool executable `dotnet-lambda-test-tool-3.1`. The path to `Amazon.Lambda.TestTool.dll` is:
 
 ```
-<home-directory>/.dotnet/tools/.store/amazon.lambda.testtool-2.1/<nuget-version>/amazon.lambda.testtool-2.1/<nuget-version>/tools/netcoreapp2.1/any/Amazon.Lambda.TestTool.dll
+<home-directory>/.dotnet/tools/.store/amazon.lambda.testtool-3.1/<nuget-version>/amazon.lambda.testtool-3.1/<nuget-version>/tools/netcoreapp3.1/any/Amazon.Lambda.TestTool.dll
 ```
 Remember when you update your version of the .NET Mock Lambda Test Tool to update the nuget versions numbers in this path string for your IDE's configuration.
 
@@ -148,6 +220,5 @@ Once this is done when you start the debugger in Visual Studio for Mac it will l
 
 ## Known Limitations
 
-* YAML based CloudFormation templates are not yet supported.
 * No mechanism for setting custom Environment variables.
 * NuGet packages that use native dependencies are not supported.
diff --git a/Tools/LambdaTestTool/Resources/TestHarness.png b/Tools/LambdaTestTool/Resources/TestHarness.png
diff --git a/Tools/LambdaTestTool/aws-lambda-test-tool-netcore.sln b/Tools/LambdaTestTool/aws-lambda-test-tool-netcore.sln
@@ -49,6 +49,11 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Amazon.Lambda.TestTool.Test
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Amazon.Lambda.TestTool.Tests.NETCore31", "tests\Amazon.Lambda.TestTool.Tests.NETCore31\Amazon.Lambda.TestTool.Tests.NETCore31.csproj", "{E57ABB02-E8FC-4011-95D3-E9CB9412EDCB}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{8B0304AF-C6CF-4B62-B1B3-3F7C045B1BC4}"
+	ProjectSection(SolutionItems) = preProject
+		README.md = README.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SharedMSBuildProjectFiles) = preSolution
 		tests\Amazon.Lambda.TestTool.Tests.Shared\Amazon.Lambda.TestTool.Tests.Shared.projitems*{594ee68c-10c0-4a19-9b61-377d0ab2f5ed}*SharedItemsImports = 5
