Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update tunneling software and instructions #2469

Merged
merged 1 commit into from
Oct 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.
Loading