为扩展配置 .NET 机器人

项目
10/25/2024

从2023年9月1日起，强烈建议使用 Azure 服务标记方法进行网络隔离。 DL-ASE的使用应仅限于高度特定的方案。在生产环境中实施此解决方案之前，我们建议咨询支持团队，以获取他们的指导。

适用于：SDK v4

本文介绍如何更新 .NET 机器人，使之可以与命名管道工作，以及如何在托管机器人的 Azure 应用服务资源中启用 Direct Line 应用服务扩展。

先决条件

一个 Azure 帐户。如果你还没有该订阅，请在开始之前先创建试用版订阅。
一个在 Azure 中部署的 .NET 机器人。
.NET BOT Framework SDK 4.14.1或更高版本。

启用 Direct Line 应用服务扩展

本部分介绍如何使用机器人 Direct Line 通道配置中的应用服务扩展密钥来启用 Direct Line 应用服务扩展。

更新机器人代码

注意

Microsoft.Bot.Builder.StreamingExtensions NuGet 预览包已弃用。从 v4.8 开始，SDK 包含命名空间 Microsoft.Bot.Builder.Streaming 。如果机器人以前使用了预览包，则必须先删除这些包，然后才能按照以下步骤操作。

在 Visual Studio 中打开机器人项目。

允许应用使用命名管道：

打开 Startup.cs 文件。
添加对 Microsoft.Bot.Builder.Integration.AspNet.Core NuGet 包的引用。
```
using Microsoft.Bot.Builder.Integration.AspNet.Core;
```

在 Configure 方法中，调用添加到 UseNamedPipes 方法。

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();
}

保存 Startup.cs 文件。

将更新的机器人部署到 Azure。

启用机器人 Direct Line 应用服务扩展

在 Azure 门户中，转到你的 Azure 机器人资源。
1. 在设置中选择通道以配置机器人接受消息的通道。
2. 如果尚未启用，请从可用通道列表中选择 Direct Line 通道以启用通道。
3. 启用 Direct Line 后，从频道页再次选择它。
4. 选择应用服务扩展选项卡。
5. 在应用服务扩展密钥下，选择相应密钥旁边的眼睛图标。
转到主页，选择页面顶部的应用服务。或者，显示门户菜单，然后选择应用服务菜单项。 Azure 将显示应用服务页。
在搜索框中，输入 Azure 机器人资源名称。资源将列出。

请注意，如果将鼠标悬停在图标或菜单项上，将获取上次查看的资源的列表。 可能会列出 Azure 机器人资源。

选择你的资源链接。

在边栏的设置部分中，选择配置菜单项。
在右侧面板中添加以下新设置：

名称值

DirectLineExtensionKey 前面复制的应用服务扩展密钥的值。

DIRECTLINE_EXTENSION_VERSION 最新

名称	值
DirectLineExtensionKey	前面复制的应用服务扩展密钥的值。
DIRECTLINE_EXTENSION_VERSION	最新

如果机器人托管在主权云或其他受限制的 Azure 云中（即，无法通过公共门户访问 Azure），则还需要添加以下新设置：

名称	值
DirectLineExtensionABSEndpoint	机器人托管的特定于 Azure 云的终结点。例如，对于 USGov 云，终结点为 `https://directline.botframework.azure.cn/v3/extension`。

单击配置部分的通用设置部分，启用 Web 套接字。
选择保存，保存这些设置。此时会重启 Azure 应用服务。

确认已配置 Direct Line 应用扩展和机器人

在浏览器中转到 https://<your_app_service>.chinacloudsites.cn/.bot。如果一切正确，页面会返回这样的 JSON 内容：

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}

v 显示 Direct Line 应用服务扩展 (ASE) 的生成版本。
k 指示扩展是否可以从其配置中读取扩展密钥。
initialized 表明扩展是否可以从 Azure AI 机器人服务下载机器人元数据。
ib 表明扩展是否能够建立与机器人的入站连接。
ob 指示扩展是否能够从机器人建立出站连接。

故障排除

如果 .bot endpoint 显示的 ib 和 ob 值为 false，则意味着机器人和 Direct Line 应用服务扩展无法相互连接。
1. 请仔细检查是否已将使用命名管道的代码已添加到机器人。
2. 确认机器人可以完全正常启动和运行。有用的工具包括在 Web 聊天中测试、连接附加通道、远程调试或日志记录。
3. 重启托管机器人的整个 Azure 应用服务，确保干净启动所有进程。
如果 .bot endpoint 的 initialized 值为 false，则意味着 Direct Line 应用服务扩展无法验证添加到机器人的上述应用程序设置的应用服务扩展密钥。
1. 确认输入的值正确。
2. 切换到机器人的 Direct Line 通道配置页上显示的备用应用服务扩展密钥。

使机器人能够使用进程外托管模型;否则，将收到 HTTP 错误 500.34 - ANCM 混合托管 错误（其中 ANCM 代表 ASP.NET 核心模块）。发生此错误是因为机器人模板默认使用 InProcess 托管模型。若要配置进程外托管，请参阅进程外托管模型。更多相关信息，请参阅 aspNetCore 元素的属性和使用web.config 配置。

如果尝试将 OAuth 与 Direct Line 应用服务扩展配合使用，并遇到错误“无法从受众声明获取机器人 AppId”，请将ClaimsIdentity上的 AudienceClaim设置为BotFrameworkHttpAdapter。为此，可以子类化适配器。例如：

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)
        });
    }
}

后续步骤

将 Web 聊天与 Direct Line 应用服务扩展配合使用

通过