A Teams Toolkit generated project has pre-defined a set of VS Code tasks in its .vscode/tasks.json. These tasks are for debugging and have corresponding arguments as inputs. This page shows the details about how these tasks are defined and how to customize with your own args.

Note: these tasks are generated by Teams Toolkit (>= 5.0.0). To use those tasks generated by Teams Toolkit (>= 4.1.0), see {Debug} Teams Toolkit VS Code Tasks page.

Aligning with the official VS Code schema, the tasks.json contains tasks top-level properties, which defines all the tasks and execution sequence used by Teams Toolkit. Following shows the summary of those pre-defined tasks:

Note: Depend on your project type, your tasks.json may contain a subset of above tasks.

For customization, all teamsfx: tasks contain args as inputs. See each section of task definition about the args schema.

This sections shows the details of each task.

This task is the entry point of all other tasks. It represents the full flow to launch Teams app locally. If you'd like to skip any step(s), just comment it out, e.g.,

{
    "label": "Start Teams App Locally",
    "dependsOn": [
        //// comment out any step(s) you'd like to skip
        // "Validate prerequisites",
        "Start local tunnel",
        "Provision",
        "Deploy",
        "Start application"
    ],
    "dependsOrder": "sequence"
}

This task is to validate prerequisites that will be used in following debugging steps. If you'd like to skip checking any prerequisite(s), just comment it out.

{
    "label": "Validate prerequisites",
    "type": "teamsfx",
    "command": "debug-check-prerequisites",
    "args": {
        "prerequisites": [
            //// comment out any checker(s) you'd like to skip
            // "nodejs",
            "m365Account",
            "portOccupancy"
        ],
        "portOccupancy": [
            3978,
            //// add or update your own port(s) to be validated
            // 9239,
            2233
        ]
    }
},

Teams Toolkit includes a node.js prerequisite check that verifies whether the version of Node.js installed in your development environment exists and meets the requirements in the engines.node field of the project's package.json file.

When you create a project using Teams Toolkit, it is fully tested and validated using the LTS version of Node.js that was available at the time of creation. The supported Node.js versions for your project are specified in the engines.node field of your package.json file.

If your project has been tested and works correctly with a different version of Node.js, you can update the engines.node field in your package.json file to reflect the supported version. Doing so will remove the warning generated by the prerequisite check.

For newly created project, there may be following ports to be validated:

• 53000: the default port for local tab service
• 3978: the default port for local bot service
• 9239: the default debugger port for local bot service
• 7071: the default port for local api/backend service
• 9229: the default debugger port for local api/backend service
• 4321: the default port for local SPFx service

This task is to start local tunnel service to make your local bot message endpoint public.

If you choose to use the dev tunnel service, the following are the required arguments:

The ports argument must be an array of objects, with each object specifying the configuration for a particular port. Each object must have the following fields:

The writeToEnvironmentFileobject may have two fields:

When writeToEnvironmentFile is included, the specified environment variables will be written to the .env file. If this field is omitted, no environment variables will be written to the file.

1. The default one used by TeamsFx templates. If you want to manually migrate your local tunnel task from a v4 project, you can use the following code to replace the old task.

{
    "label": "Start local tunnel",
    "type": "teamsfx",
    "command": "debug-start-local-tunnel",
    "args": {
        "type": "dev-tunnel",
        "ports": [
            {
                "portNumber": 3978,
                "protocol": "http",
                "access": "public",
                "writeToEnvironmentFile": {
                    "endpoint": "BOT_ENDPOINT",
                    "domain": "BOT_DOMAIN"
                }
            }
        ],
        "env": "local"
    },
    "isBackground": true,
    "problemMatcher": "$teamsfx-local-tunnel-watch"
},

2. Change port. To use another port for local bot service (e.g., 3922), you can change the one in portNumber. Note that you also need to change the port in bot code (index.js or index.ts).

{
    "label": "Start local tunnel",
    "type": "teamsfx",
    "command": "debug-start-local-tunnel",
    "args": {
        "type": "dev-tunnel",
        "ports": [
            {
                "portNumber": 3922,
                "protocol": "http",
                "access": "public",
                "writeToEnvironmentFile": {
                    "endpoint": "BOT_ENDPOINT",
                    "domain": "BOT_DOMAIN"
                }
            }
        ],
        "env": "local"
    },
    "isBackground": true,
    "problemMatcher": "$teamsfx-local-tunnel-watch"
},

If your dev environment does not support Teams Toolkit dev tunnel or you prefer to use a different tunnel solution, you can choose from a variety of options including:

1. Use ngrok and automatically set the tunnel endpoint.

If you opt to use ngrok, you can install ngrok, modify the tunnel task in .vscode/tasks.json and add the following script action to your teamsapp.local.yml file to obtain the ngrok tunnel endpoint and simplify the debugging process:

a. Update Start local tunnel task:

{
    "label": "Start local tunnel",
    "type": "shell",
    "command": "ngrok http 3978 --log=stdout --log-format=logfmt",
    "isBackground": true,
    "problemMatcher": {
        "pattern": [
            {
                "regexp": "^.*$",
                "file": 0,
                "location": 1,
                "message": 2
            }
        ],
        "background": {
            "activeOnStart": true,
            "beginsPattern": "starting web service",
            "endsPattern": "started tunnel|failed to reconnect session"
        }
    }
}

b. Add the following action in the first step of the provision lifecycle in teamsapp.local.yml:

• Linux and macOS

  provision:
    - uses: script
      with:
        run: |
          for i in {1..10}; do
            endpoint=$(curl -s localhost:4040/api/tunnels | grep -o 'https://[a-zA-Z0-9 -\.]*\.ngrok\.io')
            if [ -n "$endpoint" ]; then
              break
            fi
            sleep 10
          done
          if [ -z "$endpoint" ]; then
            echo "ERROR: Failed to find tunnel endpoint after 10 attempts."
            exit 1
          else
            echo "::set-teamsfx-env BOT_ENDPOINT=$endpoint"
            echo "::set-teamsfx-env BOT_DOMAIN=${endpoint:8}"
          fi

• Windows

  provision:
    - uses: script
      with:
        run: |
          for ($i = 1; $i -le 10; $i++) {
            $endpoint = (Invoke-WebRequest -Uri "http://localhost:4040/api/tunnels" | Select-String -Pattern 'https://[a-zA-Z0-9 -\.]*\.ngrok\.io').Matches.Value
            if ($endpoint) {
              break
            }
            sleep 10
          }
          if (-not $endpoint) {
            echo "ERROR: Failed to find tunnel endpoint after 10 attempts."
            exit 1
          } else {
            echo "::set-teamsfx-env BOT_ENDPOINT=$endpoint"
            echo "::set-teamsfx-env BOT_DOMAIN=$($endpoint.Substring(8))"
          }

2. Manually update the tunnel endpoint.

For any tunnel service, you can skip or remove the Teams Toolkit dev tunnel task and manually specify your messaging endpoint by setting it in the botFramework/create action in teamsapp.local.yml.

provision:
  - uses: botFramework/create # Create or update the bot registration on dev.botframework.com
    with:
      botId: ${{BOT_ID}}
      name: bot
      messagingEndpoint: your-messaging-endpoint
      description: ""
      channels:
        - name: msteams

{
    "label": "Start Teams App Locally",
    "dependsOn": [
        "Validate prerequisites",
        // Remove/comment out tunnel task
        // "Start local tunnel",
        "Provision",
        "Deploy",
        "Start application"
    ],
    "dependsOrder": "sequence"
}

This task executes lifecycle provision to prepare Teams app related resources required for debugging. It references teamsapp.local.yml, so the steps and actions can be customized in teamsapp.local.yml.

{
    "label": "Provision",
    "type": "teamsfx",
    "command": "provision",
    "args": {
        "env": "local"
    }
}

This task executes lifecycle deploy to build project. It references teamsapp.local.yml, so the steps and actions can be customized in teamsapp.local.yml.

{
    "label": "Build project",
    "type": "teamsfx",
    "command": "deploy",
    "args": {
        "env": "local"
    }
}

These tasks are standard VS Code shell tasks to execute npm commands on project, following the official schema defined by VS Code. For example,

• command defines the shell command to be executed
• isBackground: true means the task keeps running in the background
• problemMatcher is used to capture the begin/end or any problem from the task output

{
    "label": "Start application",
    "dependsOn": [
        "Start frontend"
    ]
},
{
    "label": "Start frontend",
    "type": "shell",
    "command": "npm run dev:teamsfx",
    "isBackground": true,
    "options": {
        "cwd": "${workspaceFolder}"
    },
    "problemMatcher": {
        "pattern": {
            "regexp": "^.*$",
            "file": 0,
            "location": 1,
            "message": 2
        },
        "background": {
            "activeOnStart": true,
            "beginsPattern": ".*",
            "endsPattern": "Compiled|Failed"
        }
    }
}

This Task is to launch your application in Teams Web Client for remote development environment (e.g. Codespaces).

{
  "label": "Launch Teams for Codespaces",
  "type": "teamsfx",
  "command": "launch-web-client",
  "args": {
    "env": "local",
    "manifestPath": "${workspaceFolder}/appPackage/manifest.json"
  }
}