你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用检测中间件调试机器人

适用于： SDK v4

本文介绍如何使用检测中间件来调试机器人。 有了此功能，Bot Framework Emulator 就可以调试出入机器人的流量并查看机器人的当前状态。 可以使用跟踪消息将数据发送给 Emulator，然后检查任意给定聊天轮次中机器人的状态。

在创建机器人快速指南 中，我们使用 EchoBot（使用 Bot Framework v4 在本地构建）来演示如何调试并检查机器人的消息状态。 也可使用 IDE 来调试机器人，或者使用 Bot Framework Emulator 进行调试，但若要调试状态，则需为机器人添加检测中间件。 提供了用于 C#、JavaScript、Java 和 Python 的检测机器人示例。

注意

Bot Framework JavaScript、C# 和 Python SDK 将继续受支持，但 Java SDK 即将停用，最终长期支持将于 2023 年 11 月结束。

使用 Java SDK 构建的现有机器人将继续正常运行。

要生成新的机器人，请考虑使用 Microsoft Copilot Studio 并阅读选择正确的助理解决方案。

有关详细信息，请参阅机器人构建的未来。

先决条件

• 具备机器人中间件和管理状态方面的知识
• 具备如何调试 SDK 优先机器人以及使用 Emulator 测试和调试方面的知识
• 安装 Bot Framework Emulator
• 安装开发隧道（如果你想调试在 Azure 中配置的机器人以使用其他通道）
• 用于 C#、JavaScript、Java 或 Python 的检测机器人样本的副本

将 Emulator 更新到最新版本

在使用机器人检测中间件调试机器人之前，请将 Emulator 更新到 4.15 版本或更高版本。 检查更新的最新版本。

若要查看 Emulator 的版本，请在菜单中选择“帮助”，然后选择“关于”。 此时就会看到 Emulator 的当前版本。

更新机器人代码

C#

检测状态和检测中间件在 Startup.cs 文件中配置，然后由适配器使用。

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

在 EchoBot.cs 文件中更新机器人类。

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

在更新机器人的代码之前，将其包更新到最新版本，方法是在终端中执行以下命令：

npm install --save botbuilder@latest

然后需更新 JavaScript 机器人的代码，如下所示。 可以在更新机器人的代码中了解详细信息，也可以参阅 GitHub 上的检测中间件示例。

index.js

在 index.js 文件中设置检测状态并将检测中间件添加到适配器。

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

在 bot.js 文件中更新机器人类。

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

在 Application.java 文件中设置检测状态并将检测中间件添加到适配器。 检测状态是通过提供新的 Spring @Bean 以提供 BotFrameworkHttpAdapter 来设置的，后者已设置为 @Primary，因此会替代 BotDependencyConfiguration 基类提供的默认 BotFrameworkHttpAdapter。 请查看以下代码更新，或参阅 GitHub 上的检测中间件示例。

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection 是作为 com.microsoft.bot.integration 包的一部分实现的，可从 Java SDK 源代码进行查看。

在 EchoBot.java 文件中更新机器人类。

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

更新机器人的代码之前，请在终端中通过运行以下命令来安装所需的 PyPI 包：

pip install aiohttp
pip install botbuilder-core>=4.7.0

通过向配适器添加中间件，在 app.py 文件中设置检查状态。

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

在 echo_bot.py 文件中更新机器人类。

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

在本地测试机器人

更新代码后，即可在本地运行机器人并使用两个 Emulator 来测试调试功能：一个用于发送和接收消息，另一个用于在调试模式下检测消息的状态。 若要在本地测试机器人：

1. 转到机器人在终端的目录，执行以下命令，在本地运行机器人：

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. 打开 Emulator。 选择“打开机器人”。 在“机器人 URL”中填充 http://localhost:3978/api/messages 以及 MicrosoftAppId 和 MicrosoftAppPassword 值。 如果使用 JavaScript 机器人，则可在机器人的 .env 文件中找到这些值。 如果使用 C# 机器人，则可在 appsettings.json 文件中找到这些值。 对于 Java 机器人，可以在 application.properties 文件中找到这些值。 选择“连接” 。

3. 现在，打开另一个 Emulator 窗口。 这第二个 Enulator 窗口将充当调试器。 请按上一步的说明操作。 勾选“在调试模式下打开”，然后单击“连接”。

4. 此时，你将在调试 Emulator 中看到带有唯一标识符 (/INSPECT attach <identifier>) 的命令。 从调试模拟器复制带有该标识符的整个命令，并将其粘贴到第一个模拟器的聊天框中。

   注意

   将检测中间件添加到机器人的代码中后，每次在调试模式下启动 Emulator 时，都会生成一个唯一标识符。

5. 现在可以将消息发送到第一个 Emulator 的聊天框中，并在调试 Emulator 中检测消息。 若要检测消息的状态，请单击调试模拟器中的“机器人状态”，然后在右侧的 JSON 窗口中展开“values”。 你将在调试 Emulator 中看到机器人的状态：

   

检测在 Azure 中配置的机器人的状态

如果想检查在 Azure 中配置并连接到通道（如 Teams）的机器人的状态，则需要安装并运行开发隧道。

运行 devtunnel

目前，你已将 Emulator 更新到最新版本，并在机器人的代码中添加了检测中间件。 下一步是运行 devtunnel，并配置本地机器人。 在运行 devtunnel 之前，需要在本地运行机器人。

若要在本地运行机器人：

1. 转到机器人在终端中的文件夹，将 npm 注册设置为使用最新版本

2. 在本地运行机器人。 可以看到机器人公开了一个端口号（例如 3978）。

3. 打开另一个命令提示符，并转到机器人的项目文件夹。 运行下面的命令：

   devtunnel host -a -p 3978
   

4. Devtunnel 现在已连接到本地运行的机器人。 复制安全 (HTTPS) 公共 URL。

   

更新机器人资源

现在，本地机器人已连接到 devtunnel，可以在 Azure 中配置机器人资源以使用 devtunnel URL。

1. 在 Azure 中转到你的机器人资源。 在左侧菜单上，选择“设置”下的“配置”。

   1. 将消息传送终结点设置为复制的 devtunnel URL 地址。 根据需要在 IP 地址后添加 /api/messages。 例如，https://0qg12llz-3978.usw2.devtunnels.ms/api/messages。

   2. 选择“启用流式处理终结点”。

      

   3. 选择“应用”以保存所做的更改。

      提示

      如果“应用”未启用，则可取消勾选“启用流式处理终结点”并选择“应用,”，然后再次勾选“启用流式处理终结点”并选择“保存”。 需确保“启用流式处理终结点”已选中且终结点配置已保存。

2. 请转到机器人的资源组。

   1. 选择“部署”，然后选择以前成功部署的机器人资源。 从左侧菜单中选择“模板”，获取与机器人关联的 Web 应用的 MicrosoftAppId 和 MicrosoftAppPassword。

      

   2. 使用 MicrosoftAppId 和 MicrosoftAppPassword 更新机器人的配置文件（C# 的 appsettings.json 或 JavaScript 的 .env）。

3. 启动 Emulator，选择“打开机器人”，并在“机器人 URL“中输入 http://localhost:3978/api/messages。 使用添加到机器人配置文件的相同 MicrosoftAppId 和 MicrosoftAppPassword 填充 Microsoft 应用 ID 和 Microsoft 应用密码。 然后选择“连接” 。

4. 正在运行的机器人现已连接到 Azure 中的机器人资源。 若要在Web 聊天中测试 Azure 中的机器人，请转到机器人资源，选择“在Web 聊天中测试”，然后将消息发送到机器人。

启用调试模式

1. 在 Emulator 中，选择“调试”，然后选择“开始调试”。

2. 为机器人 URL（例如 https://4jj51x75-51865.usw2.devtunnels.ms/api/messages）输入 devtunnel URL（别忘了添加 /api/messages）。

   1. 对于“Microsoft 应用 ID”，请输入机器人的应用 ID。
   2. 对于“Microsoft 应用密码”，请输入机器人的应用机密。
   3. 确保还勾选“在调试模式下打开”。
   4. 选择“连接” 。

3. 启用调试模式后，Emulator 将生成 UUID。 UUID 是一个独一无二的 ID，每次在 Emulator 中启动调试模式时，就会生成它。

4. 复制 UUID 并将其粘贴到通道聊天框的“在 Web 聊天中进行测试。 此时会在聊天框中看到“已附加到会话，将复制所有流量进行检测”这条消息。

可以将消息发送到已配置通道的聊天框中，开始调试机器人。 本地 Emulator 会自动使用所有用于调试的详细信息来更新消息。 若要检测机器人的消息状态，请单击“机器人状态”，然后在右侧的 JSON 窗口中展开“values”。

后续步骤

• 了解如何使用脚本文件调试机器人。
• 了解如何调试技能或技能使用者。