Configure .NET 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 .NET bot to work with named pipes and how to enable the Direct Line App Service extension in the Azure App Service resource in which you deployed your bot.

Prerequisites

  • An Azure account. If you don't already have one, create a free account before you begin.
  • A .NET bot deployed in Azure.
  • Bot Framework SDK for .NET, 4.14.1 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

Note

The Microsoft.Bot.Builder.StreamingExtensions NuGet preview packages have been deprecated. Starting with v4.8, the SDK contains a Microsoft.Bot.Builder.Streaming namespace. If a bot previously made use of the preview packages, they must be removed before following the steps below.

  1. In Visual Studio, open your bot project.
  2. Allow your app to use named pipes:

    1. Open the Startup.cs file.

    2. Add a reference to the Microsoft.Bot.Builder.Integration.AspNet.Core NuGet package.

      using Microsoft.Bot.Builder.Integration.AspNet.Core;

    3. In the Configure method, add a call to the UseNamedPipes method.

      public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseDefaultFiles()
        .UseStaticFiles()
        .UseWebSockets()
        // Allow the bot to use named pipes.
        .UseNamedPipes(System.Environment.GetEnvironmentVariable("APPSETTING_WEBSITE_SITE_NAME") + ".directline")
        .UseRouting()
        .UseAuthorization()
        .UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });

    // app.UseHttpsRedirection();
}

    4. Save the Startup.cs file.

  3. Deploy 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.us/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>.azurewebsites.net/.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.

  • Enable the bot to use the out of process hosting model; otherwise, you'll receive an HTTP Error 500.34 - ANCM Mixed Hosting error (where ANCM stands for ASP.NET Core Module). This error occurs because the bot template is using the InProcess hosting model by default. To configure out of process hosting, see Out-of-process hosting model. For more information, see Attributes of the aspNetCore element and Configuration with web.config.

  • If you attempt to use OAuth with the Direct Line App Service extension and encounter the error "Unable to get the bot AppId from the audience claim", set ClaimsIdentity to AudienceClaim on the BotFrameworkHttpAdapter. To do so, you can subclass the adapter. For example:

    public class AdapterWithStaticClaimsIdentity : BotFrameworkHttpAdapter
{
    public AdapterWithStaticClaimsIdentity(IConfiguration configuration, ILogger<BotFrameworkHttpAdapter> logger, ConversationState conversationState = null)
        : base(configuration, logger)
    {
        // Manually create the ClaimsIdentity and create a Claim with a valid AudienceClaim and the AppID for a bot using the Direct Line App Service extension.
        var appId = configuration.GetSection(MicrosoftAppCredentials.MicrosoftAppIdKey)?.Value;
        ClaimsIdentity = new ClaimsIdentity(new List<Claim>{
            new Claim(AuthenticationConstants.AudienceClaim, appId)
        });
    }
}

Next steps

Use Web Chat with the Direct Line App Service extension