Skip to content

Commit

Permalink
Update tunneling software and instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
rido-min committed Oct 1, 2024
1 parent bc1cc05 commit 003f911
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 16 deletions.
29 changes: 13 additions & 16 deletions content/CHANNELS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@

## TL;DR
1. Update your Emulator to be on version `4.5`. You can do this by selecting `Help` -> `Check for Update...`
1. Install [ngrok](https://ngrok.com/) and navigate to the ngrok executable's location in a terminal.
1. Install [DevTunnels](https://aka.ms/devtunnels/)
1. [Update your bot's code](#1-update-your-bots-code)
1. Run ngrok `./ngrok http 3979 --host-header=localhost`
1. Open your bot in the [Azure Portal](https://ms.portal.azure.com/), select the `Settings` blade and paste the ngrok url provided in the terminal into the *Messaging Endpoint* field then save. **note:** If necessary, don't forget to add the `/api/messages` endpoint.
1. Set the appropriate environment variables (prefix with EXPORT for OSX/Linux, SET for Windows):
1. Run DevTunnels `devtunnel host -a -p 3979`
1. Open your bot in the [Azure Portal](https://portal.azure.com/), 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.
1. Set the appropriate environment variables (prefix with `EXPORT` for OSX/Linux or `SET` for Windows):

```bash
NODE_ENV=development;
Expand All @@ -32,10 +32,10 @@ If you have configured your bot to [run in 1 or more channels](https://docs.micr
**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](https://blog.botframework.com/2017/03/28/Custom-Channel-Data/) protocol data and [internal bot state](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-concept-state?view=azure-bot-service-4.0) as each turn context executes throughout the conversation within a channel.

## How it works
The tunneling software [ngrok](https://ngrok.com/) 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](https://github.com/Microsoft/botbuilder-js/blob/1c790f4a4f0d761c215eb3841ff370f4b274f5d1/libraries/testbot/index.js#L21), 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.
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](https://github.com/Microsoft/botbuilder-js/blob/1c790f4a4f0d761c215eb3841ff370f4b274f5d1/libraries/testbot/index.js#L21), 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](https://github.com/Microsoft/BotFramework-Emulator/releases), [ngrok](https://ngrok.com/) and update your bot's dependencies to use BotBuilder v4.4+
If you haven't already, get the [latest Emulator](https://github.com/Microsoft/BotFramework-Emulator/releases), [Dev Tunnels](https://aka.ms/devtunnels) 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](https://github.com/Microsoft/botbuilder-js/blob/1c790f4a4f0d761c215eb3841ff370f4b274f5d1/libraries/testbot/index.js#L21) in your Bot's middleware stack:
Expand All @@ -59,22 +59,19 @@ if (process.env.MicrosoftAppId && process.env.MicrosoftAppPassword) {
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials, process.env.MicrosoftAppId, process.env.MicrosoftAppPassword))
```
### 2. Run ngrok
Open a terminal instance and run ngrok with the following command to create a new tunnel (you may need to navigate to where the ngrok executable lives on your filesystem) the port specified is the same port your bot is running on:
### 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:
OSX
```bash
./ngrok http 3978 --host-header=localhost
```
Windows
```bash
"ngrok.exe" http 3978 --host-header=localhost
devtunnel host -a -p 3978
```
Save the https entry generated by ngrok to your clipboard.
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](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-manage-settings?view=azure-bot-service-4.0) 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.
In the azure portal, [navigate to your bot's settings](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-manage-settings?view=azure-bot-service-4.0) 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
```bash
Expand Down
Binary file removed content/assets/ngrok.png
Binary file not shown.

0 comments on commit 003f911

Please sign in to comment.