Configure Node.js bot for extension

  • Article

Commencing September 1, 2023, it is strongly advised to employ the Azure Service Tag method for network isolation. The utilization of DL-ASE should be limited to highly specific scenarios. Prior to implementing this solution in a production environment, we kindly recommend consulting your support team for guidance.

APPLIES TO: SDK v4

This article describes how to update a Node.js bot to work with named pipes and how to enable the Direct Line App Service extension in the Azure App Service resource where the bot is hosted.

Prerequisites

  • An Azure account. If you don't already have one, create a trial subscription before you begin.
  • A Node.js bot deployed in Azure.
  • Bot Framework SDK for Node.js, 4.7 or later.

Enable Direct Line App Service extension

This section describes how to enable the Direct Line App Service extension using the App Service extension key from your bot's Direct Line channel configuration.

Update bot code

To allow your app to use the Direct Line App Service Extension Named Pipe:

  1. Edit your bot's index.js file.

    1. Locate the line where you create the bot's adapter.

    2. After the adapter is created, add the following statement, which will pull the App Service name from the environment and instruct the adapter to connect to the appropriate named pipe.

      • If your bot uses the CloudAdapter (recommended):

        adapter.connectNamedPipe(
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline',
    async (context) => {
        await myBot.run(context);
    },
    process.env.MicrosoftAppId,
    AuthenticationConstants.ToChannelFromBotOAuthScope);

      • If your bot uses the deprecated BotFrameworkAdapter:

        adapter.useNamedPipe(async (context) => {
    await myBot.run(context);
    },
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline'
);

    3. Save your changes.

  2. Edit your bot's web.config file to add the AspNetCore handler and rule needed by Direct Line App Service extension to service requests.

    1. Edit your bot's web.config file.

    2. Change the webSocket tag's enabled attribute to true.

      <webSocket enabled="true" />

    3. In the <handlers> section, add a registration for the following handler.

      <add name="aspNetCore" path="*/.bot/*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />

    4. In the <rewrite> section, add the following rule to the rules list.

      <!-- Do not interfere with Direct Line App Service extension requests. (This rule should be as high in the rules section as possible to avoid conflicts.) -->

<rule name ="DLASE" stopProcessing="true">
  <conditions>
    <add input="{REQUEST_URI}" pattern="^/.bot"/>
  </conditions>
</rule>

    5. Save your changes.

  3. Redeploy your updated bot to Azure.

Enable bot Direct Line App Service extension

  1. In the Azure portal, go to your Azure Bot resource.

    1. Under Settings select Channels to configure the channels your bot accepts messages from.
    2. If it isn't already enabled, select the Direct Line channel from the list of Available channels to enable the channel.
    3. After enabling Direct Line, select it again from the Channels page.
    4. Select the App Service extension tab.
    5. Under App Service Extension Keys, select the eye icon next to the corresponding key.

  2. Go to the home page and select App Services at the top of the page. Alternatively, display the portal menu and then select the App Services menu item. Azure will display the App Services page.

  3. In the search box, enter your Azure Bot resource name. Your resource will be listed.

    Notice that if you hover over the icon or the menu item, you get a list of your last viewed resources. Your Azure Bot resource will likely be listed.

  4. Select your resource link.

    1. In the Settings section, select the Configuration menu item.

    2. In the right panel, add the following settings:

      Name Value
      DirectLineExtensionKey The value of the App Service extension key you copied earlier.
      DIRECTLINE_EXTENSION_VERSION latest

    3. If your bot's hosted in a sovereign or otherwise restricted Azure cloud, where you don't access Azure via the public portal, you'll also need to add the following setting:

      Name Value
      DirectLineExtensionABSEndpoint The endpoint specific to the Azure cloud your bot is hosted in. For the USGov cloud for example, the endpoint is https://directline.botframework.azure.cn/v3/extension.

    4. From within the Configuration section, select the General settings section and turn on Web sockets.

    5. Select Save to save the settings. This restarts the Azure App Service.

Confirm the Direct Line extension and the bot are configured

In your browser, go to https://<your_app_service>.chinacloudsites.cn/.bot. If everything is correct, the page will return the following JSON content:

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}
  • v shows the build version of the Direct Line App Service extension.
  • k indicates whether the extension was able to read an extension key from its configuration.
  • initialized indicates whether the extension was able to download bot metadata from Azure AI Bot Service.
  • ib indicates whether the extension was able to establish an inbound connection to the bot.
  • ob indicates whether the extension was able to establish an outbound connection from the bot.

Troubleshooting

  • If the ib and ob values displayed by the .bot endpoint are false, the bot and the Direct Line App Service extension are unable to connect to each other.

    1. Double check the code for using named pipes has been added to the bot.
    2. Confirm the bot is able to start up and run. Useful tools are Test in WebChat, connecting an additional channel, remote debugging, or logging.
    3. Restart the entire Azure App Service the bot is hosted within, to ensure a clean start up of all processes.

  • If the initialized value of the .bot endpoint is false, the Direct Line App Service extension is unable to validate the App Service extension key added to the bot's Application Settings above.

    1. Confirm the value was correctly entered.
    2. Switch to the alternate extension key shown on your bot's Configure Direct Line page.

Next steps

Use Web Chat with the Direct Line App Service extension