Edit

Debug background process

  • Article

The debugging process involves the .vscode/launch.json and .vscode/tasks.json files to configure the debuggers in Microsoft Visual Studio Code. Visual Studio Code launches Node debugger and browser debugger, and Microsoft Edge or Google Chrome launches a new browser instance.

The debugging process workflow is as follows:

  1. launch.json file configures the debugger in Visual Studio Code.

  2. Visual Studio Code runs the compound preLaunchTask, Start Teams App Locally in .vscode/tasks.json file.

  3. Visual Studio Code then launches the debuggers specified in the compound configurations, such as Attach to Bot, Attach to Backend, Attach to Frontend, and Launch Bot.

  4. The browser debugger, Microsoft Edge or Google Chrome, launches a new browser instance and opens a webpage to load Microsoft Teams client.

Validate prerequisites

Microsoft Teams Toolkit checks the following prerequisites during the debugging process:

  • Teams Toolkit checks if Node.js is installed. If Node.js isn't installed, the debugging terminates.

  • Teams Toolkit checks if Node.js version matches the versions defined in package.json file. If the version doesn't match, Teams Toolkit displays a warning message in output channel.

  • Teams Toolkit prompts you to sign in to Microsoft 365 account, if you haven't signed in with your valid credentials.

  • Custom app upload for your developer tenant is turned on to prevent local debug termination.

  • If Ngrok isn't installed or the version doesn't match the requirement, Teams Toolkit installs Ngrok npm package ngrok@4.2.2 in ~/.fx/bin/ngrok. Ngrok binary version 2.3 is applicable for bot and message extension and is managed by Ngrok npm package in /.fx/bin/ngrok/node modules/ngrok/bin.

    Note

    Teams Toolkit project templates use the ngrok@4.3.3 npm package, which contains v2.3.40. For more information on how to get a valid license, see ngrok.

  • If Azure Functions Core Tools version 4 isn't installed or the version doesn't match the requirement, Teams Toolkit installs Azure Functions Core Tools npm package azure-functions-core-tools@3 for Windows and macOS in ~/.fx/bin/func. The Azure Functions Core Tools npm package in ~/.fx/bin/func/node_modules/azure-functions-core-tools/bin manages Azure Functions Core Tools binary. For Linux, the local debug terminates.

  • If .NET Core SDK isn't installed or the version doesn't match the requirement, Teams Toolkit installs .NET Core SDK for Windows and macOS in ~/.fx/bin/dotnet. .NET Core SDK version is applicable for Azure Functions. For Linux, the local debug terminates.

    The following table lists the .NET Core versions:

    Platform Software
    Windows, macOS (x64), and Linux 3.1 (recommended), 5.0, 6.0
    macOS (arm64) 6.0

  • If the development certificate for localhost isn't installed for tab in Windows or macOS, then Teams Toolkit prompts you to install it.

  • If Azure Functions binding extensions isn't installed, then Teams Toolkit installs Azure Functions binding extensions in api/extensions.csproj.

  • If npm packages aren't installed, then Teams Toolkit installs all npm packages applicable for tab app, bot app, message extension, and Azure Functions.

  • Teams Toolkit starts Ngrok to create an HTTP tunnel for bot and message extension.

  • If tab, bot, message extension, and Azure Functions ports aren't available, the local debug terminates.

    The following table lists the ports available for components:

    Component Port
    Tab 53000
    Bot or message extension 3978
    Node inspector for bot or message extension 9239
    Azure Functions 7071
    Node inspector for Azure Functions 9229

When you select Start Debugging (F5), Teams Toolkit output channel displays the progress and result after checking the prerequisites.

Screenshot shows the prerequisites check summary.

For more information, see validate prerequisites task.

Start local tunnel

For bot and message extension, Teams Toolkit starts a local tunnel service to make the bot messaging endpoint public. For more information, see start local tunnel task.

Create the debug resources

Teams Toolkit executes lifecycle provision defined in teamsapp.local.yml to create Teams app related resources required for debugging. For more information, see Provision task and available actions.

Build project

Teams Toolkit executes lifecycle deploy defined in teamsapp.local.yml to build the project. For more information, see Deploy task and available actions.

Take a tour of your app source code

You can view the project folders and files under Explorer in Visual Studio Code after debugging. The following table lists the files related to debugging:

Folder name Contents Debug configuration type
teamsapp.local.yml The main Teams Toolkit project file for debugging. This file defines the life cycles and actions required for debugging.
env/.env.local Environment variables file for Teams Toolkit project. The values of each environment variable are consumed or generated during debugging.
.localConfigs Environment variables file for the app code. The values of each environment variable are generated during debugging.

For more information on the project folder structure, see Teams Toolkit project.

See also