Debugging Teams App Locally with Teams Toolkit
Tags: javascript, vscode, msteams, azure
Published: 2022-03-04 06:20:43

[In the previous post](https://dev.to/azure/developing-enterprise-ready-microsoft-teams-apps-with-teams-toolkit-v30-o87), I introduced some of the new features in Teams Toolkit v3 to empower enterprise Teams developers.

In this article, I will show you the improved local debug experience in Toolkit and new features introduced in version 3.4.

First of all, you need to install Teams Toolkit extension in Visual Studio Code, or update it to the latest version if you already have it. And if this is the first time interacting with Teams Toolkit, I recommend to go through the step-by-step tutorial, [**Get started**](https://docs.microsoft.com/microsoftteams/platform/get-started/get-started-overview/?WT.mc_id=m365-58952-timura) with JavaScript on Microsoft Teams developer platform documentation first.

![Doodle summarizing this article](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/m4yakatrmrxmij5xvndt.png)

## ⌨ Debugging with "F5"

Debugging, casually referred to as _F5_ (function key) among developers, is one of the key features of [Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging/?WT.mc_id=m365-58952-timura), and this built-in debugger helps accelerate your edit, compile, and debug loop.

Teams Toolkit uses the VS Code feature to let you run your app in Teams client and debug it during the development.

To enable local debugging in Teams Toolkit, first, _make sure you are logged in with your M365 account_ under the **Accounts** section in Toolkit. Then:

1. On VS Code, go to the **Run and Debug** view in the Activity Bar 

2. Select either **Debug (Chrome)** or **Debug (Edge)** from the dropdown menu on the debug button and click the ▶️ (Start) icon

![Screenshot of VS Code showing how to manually enable the F5 Debug feature](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dv0y2e8iqu5etezsv7ps.png)

Alternatively, you can just press **F5** function key on your keyboard.

Toolkit will launch Teams client in a new Chrome or Edge browser, where you can add your app. 

> ⚠️ If this is the first time with Teams Toolkit, you will be prompted to confirm to add an SSL certificate. Please agree to continue.
> Since Teams requires https Tab hosting endpoint, a localhost development certificate will be automatically generated and installed to your system after your confirmation. 


### 📍 Using Breakpoints

[Breakpoints in VS Code](https://code.visualstudio.com/docs/editor/debugging#_breakpoints) is available in Toolkit too to debug your code for tab, bot, message extension, and Azure Functions. You can toggle the breakpoints while your app is running on Teams client on browser.

Click the left margin next to the line you wish to stop so the breakpoint will appear as a red dot 🔴. Then run the code (F5). 

Your code will pause before the marked execution. 

![Screenshot of VS Code showing debugging with breakpoints](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ghazg9cg92dixhrm4nqy.png)

Once a debug session starts, the Debug toolbar will appear on the top of the editor:

![Screenshot of VS Code showing debug toolbar](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ferur793j1hw6yfxelks.png)

- Continue / Pause `F5`
- Step Over `F10`
- Step Into `F11`
- Step Out `⇧F11`
- Restart `⇧⌘F5`
- Stop `⇧F5`
- Multi-target debug

The last action in a dropdown menu is for selecting a [multi-target debugging](https://code.visualstudio.com/docs/editor/debugging#_multitarget-debugging/?WT.mc_id=m365-58952-timura). In Teams Toolkit, selecting "Attach to Frontend" (for tabs) or "Attach to Bot" (for bots and messaging extension) will trigger a Node.js debugger, as well as Edge or Chrome debugger to launch a new browser instance and open a web page to load Teams client. "Attach to Backend" will start a Node.js debugger to attach to the Azure functions source code.

Also note that **Hot reload** is enabled in Toolkit so you can just update your code and save the changes, then your app will automatically reload and re-attach the debugger.

To end the debugging, disconnect in the floating toolbar. Once the session is terminated, it is safe to run again.

![Screenshot of VS Code showing the disconnect button in debug toolbar](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/idl99lfkerrrd3vzvv3k.png)

---

## 🐞 What's New with Local Debug Experience in Toolkit v3.4?

There are a few new features that have been added in the latest Toolkit to improve your local debugging experience.

### ✅ Prerequisite Checker

In case you wonder, when you press the F5 key, the Teams Toolkit does:

- Register your app with Azure Active Directory
- Start app services for both backend and frontend
- Start Microsoft Teams in a web browser with a command to instruct Teams to sideload the app from `localhost`
- Create an app manifest and register the app in [Teams Developer Portal](https://dev.teams.microsoft.com/home)

These processes require specific versions of Node.js, packages, various tools, also M365 credentials.

Now in Toolkit v3.4, it checks all the requirements and lists up and displays in Output channel: 

![Screenshot of VS Code showing the prerequisites checker in Output console](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/85y7jx3pw2v6z6b6vx8i.png)

This gives you more transparency and clear ideas about what is going on and easier to figure out when something goes wrong. 

### ⚙️ Customizing Local Debug Settings

Another new feature is that now Toolkit allows you to customize the debug settings. This gives you control over your debugging experience.

#### Skipping Prerequisites

You can skip some of the prerequisites in VS Code Settings: 

1. Go to Settings
2. Find **Extensions** in the list and expand it
3. Find **Teams Toolkit (Preview)** and click **Prerequisite Check**

![Screenshot of VS Code Settings](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n26b266eafjo706ho4om.png)

Now you have the checkboxes so you can uncheck the items you would like to skip.

#### Using Your Own Bot Endpoint

Teams Toolkit uses the 3rd party tool called, **ngrok** to tunnels your localhost to the internet to run bots. If you wish to use your own bot endpoint,

1. At Prerequisites Check in VS Code Settings, **uncheck** "Ensure Ngrok is installed and started. (ngrok)"

2. Set `botDomain` and `botEndpoint` configuration in `.fx/configs/localSettings.json` to your own domain and endpoint

#### Using Your Own Development Certificate

Similarly, you can use your own development certificate, 

1. At Prerequisites Check in VS Code Settings, **uncheck** "Ensure development certificate is trusted. (devCert)". 

2. Set `sslCertFile` and `sslKeyFile` configuration in `.fx/configs/localSettings.json` to your own certificate file path and key file path.

You can learn more about the certificate in [TeamsFx documentation](https://github.com/OfficeDev/TeamsFx/blob/dev/docs/fx-core/localdebug-help.md#what-to-do-if-i-do-not-want-to-install-the-development-certificate) on GitHub.

### 🔧 Manual Customizations

You can also customize your local debug settings manually with editing configuration files.

#### Using Your Own Start Scripts

_For tab:_
1. Update `dev:teamsfx` script in `tabs/package.json`. 

_For bot or messaging extension:_
1. Update `dev:teamsfx` script in `bot/package.json`. 

_For Azure functions:_
1. Update `dev:teamsfx` script in `api/package.json`. In addition for TypeScript, update `watch:teamsfx` script.

> ⚠️ The ports required by tab app, bot app, messaging extension app and Azure functions are not supported to be customized currently

#### Adding Environmental Variables

You can add environment variables to `.env.teamsfx.local` file for tab, bot, messaging extension and Azure functions. 

Teams Toolkit will load the environment variables you added to start services during local debug. 

> ⚠️ The environment variables are not supported to hot reload. You need to start a new local debug after adding new environment variables.

#### Debugging Partial Component

Teams Toolkit utilizes VS Code multi-target debugging to debug tab, bot, messaging extension and Azure functions at the same time. 

You can updates `.vscode/launch.json` and `.vscode/tasks.json` to debug partial component. Let's say, you want to debug tab only in an app with tab and bot capabilities with Azure functions project, you can take the following steps:

1. Comment out these lines in `.vscode/launch.json`:

```json
{ 
  "name": "Debug (Edge)", 
  "configurations": [ 
    "Attach to Frontend (Edge)", 
    // "Attach to Bot", 
    // "Attach to Backend" 
  ], 
  ...
```

2. Comment out these lines in `.vscode/tasks.json`:

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


---

I hope you found the article helpful for debugging your Teams apps and the new features give you more confidence debugging your Teams app development! 

Please don't hesitate to drop your comments and feedback here. 

See you until the next post 👋


## 📚 Learn More

- [Teams Toolkit documentation](https://docs.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-fundamentals?WT.mc_id=m365-58952-timura)

- [Get started with Microsoft Teams platform](https://docs.microsoft.com/microsoftteams/platform/get-started/get-started-overview/?WT.mc_id=m365-58952-timura)

---

### 📢 Shoutout 

Teams Toolkit Engineering team, especially Kuojian Lu and Yu Zhang ❤️