Document Process for Debugging Local Bot on Channels

[justinwilaby]

Document exact steps needed to connect a locally running bot to the Emulator while interacting with it using an external app or channel like Teams, Skype, Slack, etc.

[justinwilaby]

EAP Testing Instructions (Node Only)

Prerequisites

EAP Testing assumes you have a bot deployed to Azure configured to use the Teams channel.

TL;DR

1. install ngrok locally then cd to it's location in a terminal
2. run ngrok ./ngrok http 3979 --host-header=localhost
3. Open your bot in the azure portal, select the settings blade and paste the ngrok url provided in the terminal then save.
4. Clone the BotBuilder-JS repo
5. git checkout stevenic/4.4-planning
6. install lerna: npm i -g lerna then run lerna bootstrap --hoist && npm run build
7. cd samples/10. sidecarDebugging and build using npm run build
8. set your environment variables (prefix with EXPORT for mac, SET for windows):

PORT=3979;
NODE_ENV=development;
MICROSOFT_APP_ID=<your app id>;
MICROSOFT_APP_PASSWORD=<your bot's password>;
EMULATOR_URL=http://localhost:9000;

9. Run your bot: npm start
10. Open the Teams chat link provided in the azure portal in the channels blade.
11. checkout the Emulator branchjwilaby/auto-connect-emulator, build and run the Emulator as usual.
12. In the Emulator, go to the view menu and select "Sidecar debug mode" the begin chatting with your bot in teams.

Run Your Bot in a Channel While Debugging Locally

If you have configured your bot to run in 1 or more channels and would like to test a locally running bot using the Emulator while interacting with it in a communication app (Teams, Skype, Slack, WebChat, etc.), these instructions will show you how.

Since chat messages, adaptive cards, and other features have notable differences across the many available channels, the Emulator cannot reasonably account for all of them. This guide shows you how to have a locally running bot where changes can be made quickly, breakpoints can be set and the project can be rebuilt and restarted while interacting with it via an installed app like Teams or Slack.

How it works

The tunneling software ngrok is used to create a tunnel to your locally running bot. The tunnel's URL is provided to your web app bot in Azure. You build your bot with an Emulator aware Adapter, run it locally then chat with it in Teams or any other available channel. The Emulator still receives the conversation's message exchange as usual.

Let's get Started

If you haven't already, get the latest Emulator, ngrok and update your bot's dependencies to use BotBuilder v4.4+

1. Update Your Bot's Code

Your bot will need to become "Emulator Aware" in order to connect to and send the conversation exchange to the Emulator. Include the BotDebugger class somewhere in your bot's code:

Then set the EMULATOR_URL environment variable to http://localhost:9000 prior to launching your bot. On a mac, this is done using this command:

export EMULATOR_URL=http://localhost:9000

Alternatively, you can refer to documentation in VS Code for setting up environment variables in the launch configs for your bot.

2. Run ngrok

Open a terminal and run ngrok with the following command to create a new tunnel:

./ngrok http 3979 --host-header=localhost

The output in the terminal should look something like this:

3. Update Azure to Point to the Tunnel

In the azure portal, navigate to your bot's settings and paste the
url provided by the ngrok terminal in the Messaging endpoint field and save the changes. Do not forget to use /api/messages. It's best to create a Bot in Azure that is used specifically for this purpose. Do not overwrite
the messaging endpoint of a deployed production bot.

4. Connect to a Channel

If you haven't already done so, connect your bot to a channel. You may also need to download and install the app
associated with the channel if you have't already.

5. Debug!

Run your bot locally, then open the Emulator. In the Emulator choose file > Sidecar Debug Mode.

This will place the Emulator in a read only mode an enable inbound connections from your locally running bot. Begin chatting with your bot in Teams, Skype, Slack or WebChat. Once the first message is received, your bot will connect to the Emulator and send it the conversation exchange.