Introducing launch configurations support for SAM debugging in the AWS Toolkit for VS Code

The AWS Toolkit for Visual Studio Code implements a new SAM debugging experience based on VS Code launch configurations. This new experience replaces the old Run Locally | Debug Locally experience. To try the SAM debugging experience for VS Code, install the AWS Toolkit from the VS Code Marketplace. The new experience embraces VS Code’s standard debugger experience, from configuration, to running and debugging, and stepping through code.

The AWS Toolkit connects VS Code to the SAM CLI. Users can define a config in VS Code, launch it, and the AWS Toolkit will invoke SAM CLI to build the serverless project, deploy the code to a local Docker instance, invoke the Lambda in Docker, and connect VS Code to the Docker process, allowing the user to step-through their Lambda code in VS Code.

What’s New

The new SAM debug experience for the AWS Toolkit allows you to use VS Code’s standard launch configuration interface to run and debug Lambda handlers locally. Besides providing a more integrated and idiomatic experience, aws-sam launch configurations give users more flexibility to configure launchers for any SAM template or handler.

SAM local Lambda debugging also includes new capabilities that allow the user to:

• specify AWS credentials (the aws field of the launch config)
• specify SAM CLI options (the sam field of the launch config)
• debug a Lambda locally without a SAM template.yaml file, by specifying target: code in the invokeTarget of the launch-config

Usage

The updated AWS Toolkit allows you to run or debug AWS SAM Lambdas locally by running a launch config of type: aws-sam.

Step 1. Create a launch config for a SAM Lambda using any of the following approaches:

• Visit the template.yaml in your SAM project, place the cursor on a lambda resource, and click the Add Debug Configuration CodeLens. This will add a pre-populated launch config to your launch.json.
• Alternative: visit the handler source code (.js, .cs, or .py file) in your SAM project, place the cursor on a lambda handler, and click the Add Debug Configuration CodeLens. This will add a pre-populated launch config to your launch.json.
• Alternative: Edit launch.json and create a new item by hand (where projectRoot points to a valid directory, lambdaHandler is the name of the handler, and runtime is a valid runtime (nodejs12.x, python3.7, dotnetcore2.1, …)):

{
        "type": "aws-sam",
        "request": "direct-invoke",
        "name": "my-config",
        "invokeTarget": {
            "target": "code",
            "projectRoot": "src",
            "lambdaHandler": "myHandler"
        },
        "lambda": {
            "runtime": "nodejs12.x",
            "event": {},
            "environmentVariables": {}
        },
        "sam": {}
        "aws": {}
     },

Step 2: Visit the “Run” panel in the VS Code sidebar.

Select the launch config from the Run panel menu. Click the “play” button in the Run panel, or press F5.

Next Steps

In this post we overviewed new improvements in the SAM debugging experience in the AWS Toolkit for VS Code IDE. Install the Toolkit to try these features and check out the user guide to learn more. Another great place to engage with the team is on GitHub. The AWS Toolkit for VS Code is an open source project. Share your feedback and feature request issues on GitHub, or via the built-in feedback tool in the IDE plugin.