{Debug} Teams Toolkit v5 VS Code Tasks

Teams Toolkit v5 VS Code Tasks

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.

Overall Contract

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:

Task Label                      (Type:Command)	Description
Start Teams App Locally	The entry task of debugging, to be referenced by launch.json.
Validate prerequisites (teamsfx:debug-check-prerequisites)	Check prerequisites required by debugging.
Start local tunnel (teamsfx:debug-start-local-tunnel)	Start local tunneling for bot project.
Create resources (teamsfx:provision)	Create Teams app related resources required by debugging.
Build project (teamsfx:deploy)	Build project.
Start application (shell:npm run ...)	Launch all local services.

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.

Task Definition

This sections shows the details of each task.

Start Teams App Locally

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",
        "Create resources",
        "Build project",
        "Start application"
    ],
    "dependsOrder": "sequence"
}

Validate prerequisites

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.

Arguments	type	required	description
prerequisites	array	required	The enabled prerequisite checkers. Checkers: nodejs, m365Account, devCert, portOccupancy
portOccupancy	array	required	The ports to check if they are in use.

prerequisites	description
nodejs	Validate if Node.js is installed.
m365Account	Sign-in prompt for Microsoft 365 account, then validate if the account enables the sideloading permission.
devCert	Install localhost SSL certificate. It's used to serve the development sites over HTTPS to debug the Tab app in Teams.
portOccupancy	Validate available ports to ensure those debugging ones are not occupied.

Sample

{
    "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
        ]
    }
},

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

Start local tunnel

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

Arguments	Type	Required	Description
ngrokArgs	string or string[]	required	The ngrok command line arguments to start the tunnel. Full references can be found in ngrok document.
env	string	optional	The environment name. Teams Toolkit will write the environment variables defined in output to .env.<env> file.
output	object	optional	The key of tunnel endpoint and tunnel domain environment variables that will be writen to .env file.
ngrokPath	string	optional	The ngrok binary path. If undefined, use Teams Toolkit ngrok, otherwise use provided path. E.g.,"ngrokPath": "ngrok" // use ngrok from env:PATH "C:/some-path/ngrok" // use ngrok from absolute path "./bot/my-ngrok/ngrok" // use ngrok from relative path
tunnelInspection	string	optional	Teams Toolkit tries to get tunnel public URL from ngrok log first, then the first PublicURL via default inspection "http://127.0.0.1:4040/api/tunnels". If you specify your own ngrokArgs with different log format or inspection, set this arg to provide your own inspection location.

output	description
endpoint	The key of tunnel endpoint environment variable.
domain	The key of tunnel domain environment variable.

Sample

1. The default one used by TeamsFx templates. Teams Toolkit installs its own ngrok binary and start tunnel with command ngrok http 3978 --log=stdout --log-format=logfmt.

{
    "label": "Start local tunnel",
    "type": "teamsfx",
    "command": "debug-start-local-tunnel",
    "args": {
        "ngrokArgs": "http 3978 --log=stdout --log-format=logfmt",
        "env": "local",
        "output": {
            // output to .env.local
            "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
            "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
        }
    },
    "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 ngrokArgs. 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": {
        // change port here
        "ngrokArgs": "http 3922 --log=stdout --log-format=logfmt",
        "env": "local",
        "output": {
            // output to .env.local
            "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
            "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
        }
    },
    "isBackground": true,
    "problemMatcher": "$teamsfx-local-tunnel-watch"
},

3. Use your own ngrok command or config. If you'd like to use your own ngork command (e.g., ngrok start) or config (e.g., any-ngrok.yml) for advances usages. Note that if you change the log format or set your own inspect path, you need to provide tunnelInspection as well.

{
    "label": "Start local tunnel",
    "type": "teamsfx",
    "command": "debug-start-local-tunnel",
    "args": {
        // change the command here
        "ngrokArgs": "start --config any-ngrok.yml",
        // to let Teams Toolkit know your ngrok endpoint
        "tunnelInspection": "http://127.0.0.1:4040/api/tunnels",
        "env": "local",
        "output": {
            // output to .env.local
            "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
            "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
        }
    },
    "isBackground": true,
    "problemMatcher": "$teamsfx-local-tunnel-watch"
},

4. Use your own ngrok binary. If Teams Toolkit has issue on installing ngrok or you'd like to use your own ngrok binary, set ngrokPath.

{
    "label": "Start local tunnel",
    "type": "teamsfx",
    "command": "debug-start-local-tunnel",
    "args": {
        "ngrokArgs": "http 3978 --log=stdout --log-format=logfmt",
        // set ngrok path
        "ngrokPath": "/path/to/your/ngrok",
        "env": "local",
        "output": {
            // output to .env.local
            "endpoint": "BOT_ENDPOINT", // output tunnel endpoint as BOT_ENDPOINT
            "domain": "BOT_DOMAIN" // output tunnel domain as BOT_DOMAIN
        }
    },
    "isBackground": true,
    "problemMatcher": "$teamsfx-local-tunnel-watch"
},

5. Totally get rid of ngrok. If your dev environment does not support ngrok or you'd like to use your own tunnel solution, you can skip/remove this tunnel task and just let Teams Toolkit know your messaging endpoint (set your messaging endpoint in botFramework/create action in teamsapp.local.yml).

Alternative	Description
Cloud VM	Develop your project on cloud VM (e.g., Azure VMs or Azure DevTest Labs). You can choose either to still use ngrok on your cloud VM, or to directly expose your bot service via VM's public hostname and port.
localtunnel	An alternative tunnel solution. You can install and run localtunnel instead of ngrok.

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",
        "Create resources",
        "Build project",
        "Start application"
    ],
    "dependsOrder": "sequence"
}

Create resources

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.

Arguments	Type	Required	Description
template	string	required	File path of .yml template that defines the actions.
env	string	required	Environment name.

Sample

{
    "label": "Create resources",
    "type": "teamsfx",
    "command": "provision",
    "args": {
        "template": "${workspaceFolder}/teamsapp.local.yml",
        "env": "local"
    }
}

Build project

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.

Arguments	Type	Required	Description
template	string	required	File path of .yml template that defines the actions.
env	string	required	Environment name.

Sample

{
    "label": "Build project",
    "type": "teamsfx",
    "command": "deploy",
    "args": {
        "template": "${workspaceFolder}/teamsapp.local.yml",
        "env": "local"
    }
}

Start application

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

Sample

{
    "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"
        }
    }
}