Skip to content

Latest commit

 

History

History
114 lines (80 loc) · 7.75 KB

CHANNELS.md

File metadata and controls

114 lines (80 loc) · 7.75 KB
Raw

Getting started with the Bot Inspector

jump to Bot State Inspection

Prerequisites

  • A bot configured in Azure configured to use the additional channels. (Microsoft Teams, etc).
  • The latest Emulator

TL;DR

  1. Update your Emulator to be on version 4.5. You can do this by selecting Help -> Check for Update...
  2. Install DevTunnels
  3. Update your bot's code
  4. Run DevTunnels devtunnel host -a -p 3979
  5. Open your bot in the Azure Portal, select the Settings blade and paste the devtunnel url provided in the terminal into the Messaging Endpoint field then save. note: If necessary, don't forget to add the /api/messages endpoint.
  6. Set the appropriate environment variables (prefix with EXPORT for OSX/Linux or SET for Windows):
NODE_ENV=development;
MicrosoftAppId=<your app id>;
MicrosoftAppPassword=<your bot's password>;
  1. Run your bot: npm start
  2. Open the respective channel's chat link provided in the Azure Portal in the Channels blade.
  3. Open the Emulator and toggle to Bot Inspector mode via View -> Bot Inspector Mode
  4. Connect to your locally running Bot by pasting the URL to the Bot's endpoint in the connection modal. note: if configured with an external channel you may need to supply your Microsoft App Id & Microsoft App password.
  5. Copy the /INSPECT attach <UUID> command rendered in the Conversation window and paste it into your configured channel's chat.

Run Your Bot in an external Channel and observing with the Bot Framework Emulator

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.

Note: Since chat messages, Adaptive Cards, and other features have notable differences across the many available channels, the Emulator cannot visually recreate all experiences at this time. Instead, the Emulator provides the inspection of channel-specific protocol data and internal bot state as each turn context executes throughout the conversation within a channel.

How it works

The tunneling software 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 the BotBuilder 4.4 InspectionMiddleware, and run it locally, chatting with it in Teams or another configured channel. The Emulator will receive the conversation's message exchange as usual, and some internal bot state information now being exposed through this middleware.

Let's get Started

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

1. Update Your Bot's Code

Your bot will need to configure the Bot Inspector middleware in order to connect to and send the conversation exchange to the Emulator. Include the InspectionMiddleware in your Bot's middleware stack:

const { MemoryStorage, UserState, ConversationState, InspectionState, InspectionMiddleware } = require('botbuilder')
const { MicrosoftAppCredentials } = require('botframework-connector')

let memoryStorage = new MemoryStorage();
let inspectionState = new InspectionState(memoryStorage);

let userState = new UserState(memoryStorage);
let conversationState = new ConversationState(memoryStorage)

let credentials = undefined;
if (process.env.MicrosoftAppId && process.env.MicrosoftAppPassword) {
  credentials = new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword);
}

// Do not forget to provide your MicrosoftAppId & MicrosoftAppPassword in the InspectionMiddleware constructor parameters
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials, process.env.MicrosoftAppId, process.env.MicrosoftAppPassword))

2. Run Dev Tunnels

Open a terminal instance and run Dev Tunnels with the following command to create a new tunnel the port specified is the same port your bot is running on:

devtunnel host -a -p 3978

Save the https entry generated by DevTunnels to your clipboard.

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 devtunnel 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. Set the appropriate environment variables in your Bot's running process & start the Bot

MicrosoftAppId=<your app id>;
MicrosoftAppPassword=<your bot's password>;

Node

node index.js

C#

dotnet run

5. Connect to a Channel & start a conversation in it

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. Afterwards, open the respective chat link provided in the Azure Portal in the Channels blade.

6. Start up the Emulator

Open the Emulator if it isn't open already.

7. Connect to your locally running Bot

Connect to your bot by selecting Open Bot and provide the appropriate fields. Select the "Open in debug mode" checkbox. Don't forget the MicrosoftAppId & MicrosoftAppPassword if configured to use an external channel.

8. Copy the /INSPECT attach <UUID> command rendered in the Conversation window and paste it into the configured channel's chat

A successful connection to the bot with the InspectionMiddleware configured will render the text that you see above. We need to save this text and paste it in to the channel you intend to have the conversation in. You can do this few ways. The easiest is by right-clicking on the rendered message and selecting "Copy text" from the context menu.

9. Have conversation in external channel

Have a normal conversation with your Bot in your configured channel, and while doing so you will see information populating in your connected conversation in the Emulator.

Note: You can also have a normal conversation with your bot in the Emulator directly, by connecting to the bot via traditional means (Open Bot) and not selecting the "Open in debug mode" checkbox.

Bot State Inspection

The Bot Inspector now renders the Bot State for each Turn Context executed in the Bot's runtime. You can view this by selecting the Bot State element rendered in the Conversation control and then clicking the View diff button in the inspector panel that appears. At this point you can toggle between Bot States, seeing the state diff across each turn.

Have fun! And please provide any feedback by filing a new issue on the Bot Framework Emulator Github Project