Debug your Teams app

Teams Toolkit helps you to debug and preview your Microsoft Teams app. Debug is the process of checking, detecting, and correcting issues or bugs to ensure the program runs successfully in Teams.

Debug your Teams app for Visual Studio Code

Teams Toolkit in Microsoft Visual Studio Code automates the debug process. You can detect errors and fix them as well as preview the teams app. You can also customize debug settings to create your tab or bot.

Debug your Microsoft Teams app for Visual Studio Code

Teams Toolkit in Visual Studio Code automates the debug process. You can detect errors and fix them as well as preview the teams app. You can also customize debug settings to create your tab or bot.

During the debug process:

  • Teams Toolkit automatically starts app services, launches debuggers, and sideloads the Teams app.
  • Teams Toolkit checks the prerequisites during the debug background process.
  • Your Teams app is available for preview in Teams web client locally after debugging.
  • You can also customize debug settings to use your bot endpoints, development certificate, or debug partial component to load your configured app.
  • Microsoft Visual Studio Code allows you to debug tab, bot, message extension, and Azure Functions.

Key debug features of Teams Toolkit

Teams Toolkit supports the following debug features:

Teams Toolkit performs background functions during debug process, which include verifying the prerequisites required for debug. You can see the progress of the verification process in the output channel of Teams Toolkit. In the setup process you can register and configure your Teams app.

Start debugging

You can press F5 as a single operation to start debugging. The Teams Toolkit starts to check prerequisites, registers Azure AD app, Teams app, and registers bot, starts services, and launches browser.

Multi-target debugging

Teams Toolkit utilizes multi-target debugging feature to debug tab, bot, message extension, and Azure Functions at the same time.

Toggle breakpoints

You can toggle breakpoints on the source codes of tabs, bots, message extensions, and Azure Functions. The breakpoints execute when you interact with the Teams app in a web browser. The following image shows toggle breakpoint:

toggle breakpoints

Hot reload

You can update and save the source codes of tab, bot, message extension, and Azure Functions at the same time when you're debugging the Teams app. The app reloads and the debugger reattaches to the programming languages.

hot-reload for source codes

Stop debugging

When you complete local debug, you can select Stop (Shift+F5) or [Alt] Disconnect (Shift+F5) from the floating debugging toolbar to stop all debug sessions and terminate tasks. The following image shows the stop debug action:

stop debugging

Prepare for debug

The following steps help you to prepare for debug:

Sign in to Microsoft 365

If you've signed up for Microsoft 365 already, sign in to Microsoft 365. For more information, see Microsoft 365 developer program

Toggle breakpoints

Ensure that you can toggle breakpoints on the source codes of tabs, bots, message extensions, and Azure Functions for more information, see Toggle breakpoints

Customize debug settings

Teams Toolkit allows you to customize the debug settings to create your tab or bot. For more information on the full list of customizable options, see debug settings doc.

Customize Scenarios


Skip prerequisite checks

In .fx/configs/tasks.json under "Validate & install prerequisites" > "args" > "prerequisites", update the prerequisite checks you wish to skip.

skip the prerequisite checks

Use your development certificate
  1. In .fx/configs/tasks.json, uncheck "devCert" under "Validate & install prerequisites" > "args" > "prerequisites".
  2. Set "SSL_CRT_FILE" and "SSL_KEY_FILE" in .env.teamsfx.local to your certificate file path and key file path.
Customize npm install args

In .fx/configs/tasks.json, set npmInstallArgs under "Install npm packages".

Install npm package

Modify ports
  • Bot
    1. Search for "3978" across your project and look for appearances in tasks.json, ngrok.yml and index.js.
    2. Replace it with your port. Replace your port for bot
  • Tab
    1. In .fx/configs/tasks.json, search for "53000".
    2. Replace it with your port. Replace your port for tab
Use your own app package

In .fx/configs/tasks.json, set "appPackagePath" under "Build & upload Teams manifest" to your app package's path.

use your own app package path

Use your own tunnel
  1. In .fx/configs/tasks.json under "Start Teams App Locally", you can update "Start Local tunnel".

    Use your own tunnel

  2. Launch your own tunnel service then update "botMessagingEndpoint" to your own message endpoint in .fx/configs/tasks.json under "Set up bot".

    update messaging endpoint

Add environment variables

You can add environment variables to .env.teamsfx.local file for tab, bot, message extension, and Azure Functions. Teams Toolkit loads the environment variables you added to start services during local debug.

Note

Ensure to start a new local debug after you add new environment variables, as the environment variables don't support hot reload.

Debug partial component

Teams Toolkit utilizes Visual Studio Code multi-target debugging to debug tab, bot, message extension, and Azure Functions at the same time. You can update .vscode/launch.json and .vscode/tasks.json to debug partial component. If you want to debug tab only in a tab plus bot with Azure Functions project, use the following steps:

  1. Update "Attach to Bot" and "Attach to Backend" from debug compound in .vscode/launch.json.

    {
        "name": "Debug (Edge)",
         "configurations": [
            "Attach to Frontend (Edge)",
            // "Attach to Bot",
            // "Attach to Backend""
            ],
            "preLaunchTask": "Pre Debug Check & Start All",
            "presentation": {
                "group": "all",
                "order": 1
            },
            "stopAll": true
    
    }
    
  2. Update "Start Backend" and "Start Bot" from Start All task in .vscode/tasks.json.

    {
    
        "label": "Start All",
        "dependsOn": [
            "Start Frontend",
              // "Start Backend",
              // "Start Bot"
    
          ]
    
    }
    

Next

Debug your Teams app using Visual Studio

Teams Toolkit automates app startup services, initiates debug, and side loads Teams app. After debug, you can preview the Teams app in Teams web client. You can also customize debug settings to use your bot endpoints, or environment variables to load your configured app. Visual Studio allows you to debug tab, bot, and message extension. During the debug process, Teams Toolkit supports the following debug features:

  • Prepare Teams app dependencies
  • Start debugging
  • Toggle breakpoints
  • Hot reload
  • Stop debugging

Prerequisites

  Install For using...
  Required  
  Visual Studio 2022 version 17.3 You can install the enterprise edition of Visual Studio, and install the "ASP.NET "workload and Microsoft Teams Development Tools.
  Teams Toolkit A Visual Studio extension that creates a project scaffolding for your app. Use latest version.
  Microsoft Teams Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, call - all in one place.
  Prepare your Microsoft 365 tenant Access to Teams account with the appropriate permissions to install an app.
  Microsoft 365 developer account Access to Teams account with the appropriate permissions to install an app.
  Azure Tools and Microsoft Azure CLI Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.
  Optional  
  Ngrok Ngrok is used to forward external messages from Azure Bot Framework to your local machine.

Key features of Teams Toolkit

You can see the following key features of Teams Toolkit, that automate the local debugging process of your Teams app:

Prepare Teams app dependencies

Teams Toolkit prepares local debug dependencies and registers your Teams app in the tenant in your account. For Bot and Message Extension apps, Teams Toolkit will register and configure bot.

Start debugging

You can perform debugging with a single operation, press F5 to start debugging. Teams Toolkit builds code, starts services, and the launches app in your browser.

Toggle breakpoints

You can toggle breakpoints in the source codes of tabs, bots, message extensions, and Azure functions. The breakpoints execute when you interact with the Teams app in your web browser. The following image shows the toggle breakpoints:

Local debug toggle breakpoints

Hot reload

Select Hot Reload to apply your changes in your Teams app when you want to update and save the source codes simultaneously during debugging.

Select hot reload icon

Select the option Hot Reload on File Save from the drop-down to enable auto hot reload.

Select hot reload on file save

Tip

To learn more about Hot Reload function of Visual Studio during debug you can visit https://aka.ms/teamsfx-vs-hotreload.

Stop debugging

Select Stop Debugging when the local debug is complete.

Select stop debug icon

Customize debug settings

You can customize debug setting for your Teams app to use your bot endpoints and add environment variables:

Use your bot endpoint

You can set siteEndpoint configuration in .fx/configs/config.local.json to your endpoint.

"bot": {
    "siteEndpoint": "https://baidu.com"
}

Add environment variables

You can add environmentVariables to launchSettings.json file.

Add custom environment variables

Launch Teams app as a web app

You can launch Teams app as a web app instead of running in Teams client.

  1. Select Properties > launchSettings.json in Solution Explorer panel under your project.

  2. Remove the 'launchUrl' from the file.

    Launch teams as a web app by removing launchurl

  3. Right-click on Solution and select Properties.

    Right click solution and select properties

  4. Select Configuration Properties > Configuration in the dialog box.

  5. Clear the Deploy checkbox.

  6. Select OK.

    Uncheck deploy in configuration properties

See also