Run your app in Teams, but debug locally using ngrok: here’s how

If you’ve done any Teams development, Bot Framework development, or any development that involves writing code that’s ultimately executed elsewhere then you’ll be familiar with the debug problem.

The best experience as a developer is to run code locally, where you can add breakpoints, step through it, examine all the variables, and really understand what’s happening. However, despite your best intentions sometimes code runs differently to what you expected once you push it remotely. Once it’s running remotely however you don’t have as much visibility about what’s going on – unless you’ve put in enough logging in the right places (which never happens).

For writing apps in Teams there are a number of tools that can help, especially around writing bots.

Local Emulator

There is a Bot Framework Emulator which allows you to run your code locally but interact with it as though it were deployed into the Bot Framework. It’s free to use, and you can download it from GitHub (if that list of links looks scary, most people running Visual Studio on Windows will want botframework-emulator-Setup-3.5.35.exe).

To use it, compile and run your Bot Framework project so that the WebAPI listener is running and you see the landing page:

Then, run the emulator and set the endpoint URL to that local address, adding /api/messages. For instance: http://localhost:3979/api/messages.

Leave the Microsoft App ID and Microsoft App Password empty unless you’ve already set these in your web.config (in which case, fill them in!) and click Connect. Check the Log to make sure you’re connecting OK and if you are, then try sending a message. Everything is running locally so you can break/debug as you’d expect:

ngrok

The Emulator is great because it’s really easy to get going with, and gives you an immediate way to validate that your bot code is working OK.

However, if you’re writing things like tabs or compose extensions, or responding to Teams-specific behavior (like being added to a channel, being mentioned etc) then you’ll find that the Emulator doesn’t quite give you everything you need.

What you really want is to be able to access your bot in the Teams client, but have the code running locally. Luckily, that’s what ngrok can do.

ngrok is a tunnelling service – meaning they provide you with a URL which tunnels all the way back to your machine. It also supports https as well, which is critical to making this work in Bot Framework. You can use ngrok for free, there is also a paid plan which lets you have dedicated URLs.

As far as Teams and Bot Framework are concerned, the ngrok URL is “the” URL for your bot/webpage. There’s no difference in the setup.

Here’s what you do to set up a Bot Framework bot to use ngrok. I’m going to assume that you’ve already setup and provisioned a bot in Azure. (if you’ve never done this before then there’s a walkthrough here).

Firstly, download the ngrok exe and copy it someone on your machine (the same machine you have Visual Studio on).

Open a command prompt and navigate to where you copied it to. This command will open a new tunnel directly to port 3979 on your localhost. Obviously, you want to make sure that this port number lines up with where you are hosting your code locally:

ngrok http 3979 --host-header=localhost

All being well, your new URL will be shown in the console window:

Copy the https link, and head over to the Azure portal. Open the settings for your bot instance. We need to change the URL that Bot Framework service has for our bot to the ngrok one:

Don’t forget to include the /api/messages on the end.

If you haven’t already then make sure that your local web.config includes both the AppID and AppPassword for your bot (this always catches me out!)

Now, making sure your code is running, then try doing something which will send a message to your bot (like sending it a direct chat, or mentioning it in a channel). You should find that it’s now executing local code and that you can breakpoint it. In the screenshot below, notice that the message text from the Teams client has made it through to my local code:

Obviously, you should only be doing this on non-live bots which are in development – otherwise you’re going to get ALL the traffic coming to your local machine! That said though, it’s a really useful way of getting rich information and insight into how stuff performs in Teams, what data you can get from Teams, and how the flow of control and information between Teams, the Bot Framework and your app actually works.

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Step Into Remote Code with VS Remote Debugging Building an Out of Office reminder with the new Microsoft Teams Connector for Microsoft Flow Developing for Microsoft Teams Microsoft Teams to get PowerShell Commands to Manage Teams Using Microsoft Teams as a Developer Video