Configure .NET bot for extension
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 where the bot is hosted.
Prerequisites
- 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.
In Visual Studio, open your bot project.
Allow your app to use named pipes:
- Open the Startup.cs file.
- In the
Configuremethod, add a call to theUseNamedPipesmethod.
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(); }Save the Startup.cs file.
Deploy your updated bot to Azure.
Enable bot Direct Line App Service extension
In the Azure portal, go to your Azure Bot resource.
- From the left panel menu under Bot management select Channels to configure the Azure Bot Service channels your bot accepts messages from.
- If it is not already enabled, select the Direct Line channel and follow instructions to enable the channel.
- In the Connect to channels table select the Edit link on the Direct Line row.
- Scroll down to the App Service extension Keys section.
- Select the Show link to reveal one of the keys. Copy this value for use later.
Go to the home page, select App Services at the top of the page. Alternatively, display the portal menu and then select the App Services menu item, in the left panel. Azure displays the App Services page.
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 the list of the last resources you viewed. Chances are your Azure Bot resource will be listed.
Select your resource link.
In the Settings section, select the Configuration menu item.
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 If your bot is hosted in a sovereign or otherwise restricted Azure cloud, where you don't access Azure via the public portal, you will 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.Still within the Configuration section, select the General settings section and turn on Web sockets.
Select Save to save the settings. This restarts the Azure App Service.
Confirm the extension and the bot are configured
In your browser, navigate to https://<your_app_service>.azurewebsites.net/.bot.
If everything is correct, the page will return this JSON content: {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}. This is the information you obtain when everything works correctly, where
- v displays the build version of the Direct Line App Service extension.
- k determines whether the extension can read an extension key from its configuration.
- initialized determines whether the extension can use the extension key to download the bot metadata from Azure Bot Service.
- ib determines whether the extension can establish an inbound connection with the bot.
- ob determines whether the extension can establish an outbound connection with the bot.
Troubleshooting
If the ib and ob values displayed by the .bot endpoint are false this means the bot and the Direct Line App Service extension are unable to connect to each other.
- Double check the code for using named pipes has been added to the bot.
- Confirm the bot is able to start up and run at all. Useful tools are Test in WebChat, connecting an additional channel, remote debugging, or logging.
- 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 it means the Direct Line App Service extension is unable to validate the App Service extension key added to the bot's Application Settings above.
- Confirm the value was correctly entered.
- 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 will receive an HTTP Error 500.34 - ANCM Mixed Hosting. Where ANCM stands for ASP.NET Core Module. The error is caused because the bot template is using the
InProcesshosting model by default. To configure out of process hosting, see Out-of-process hosting model. See also 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." A
ClaimsIdentitywith theAudienceClaimassigned needs to be set on theBotFrameworkHttpAdapter. In order to accomplish this a developer may 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) }); } }