Debug a bot from any channel using ngrok

APPLIES TO: SDK v4

When your bot is in development, you can debug your bot locally using an IDE such as Visual Studio or Visual Studio Code. You can also debug a bot using the Bot Framework Emulator by chatting with your bot locally and inspect the messages your bot sends and receives. You can even make slight updates of your bot's code and enable the feature to debug a bot with inspection middleware.

When your bot is already in production, you can debug your bot from any channel using ngrok. The seamless connection of your bot to multiple channels is a key feature available in Bot Framework. In this article, we will show you how to locally debug your bot from any channel your production bot is configured for, using ngrok. We used an EchoBot sample connected to Microsoft Teams Channel throughout the article for instruction.

Prerequisites

Run ngrok

ngrok is a cross-platform application that "allows you to expose a web server running on your local machine to the internet." Essentially, what we'll be doing is using ngrok to forward messages from external channels on the web directly to our local machine to allow debugging, as opposed to the standard messaging endpoint configured in the Azure portal.

  1. Open a terminal and navigate to the folder where your ngrok executable is.

  2. Run ngrok with the following command to create a new tunnel.

    ngrok http 3978 -host-header="localhost:3978"
    

    Note

    Please note that the port specified is the port your bot is running on. You may use any localhost port you'd like.

  3. When ngrok starts, copy and save the public forwarding URL for later.

    ngrok forwarding url

Configure in Azure portal

While ngrok is running, login to your Azure portal and view your bot settings to do some configuration.

  1. Select your Bot Channels Registration connected to your local bot.

  2. Scroll down to Configuration. Copy and paste the ngrok forwarding URL in the Messaging endpoint field. Ensure that you maintain "/api/messages" at the end of the URL.

    messaging endpoint

  3. Scroll up and select Save.

Test

At this point, incoming messages from to your bot from external channels will now be sent to your local bot. The sample bot we'll use to demonstrate this is already configured live for Microsoft Teams. Read Connect a bot to Microsoft Teams about connecting a local bot with Microsoft Teams channel.

teams channel

Locally, you can set breakpoints in Visual Studio. Expanding the text property from the incoming activity object, you will see that the message you sent the bot from teams is being intercepted locally for you to debug.

set breakpoints

From here you can debug normally, and run your code step by step. You can use this to debug your bot from any channel.

debug continue

Additional information