使用檢查中間件對 Bot 進行偵錯

適用於： SDK v4

本文說明如何使用檢查中間件對 Bot 進行偵錯。 這項功能可讓 Bot Framework 模擬器對進出 Bot 的流量進行偵錯，並查看 Bot 的目前狀態。 您可以使用追蹤訊息將數據傳送至模擬器，然後在對話的任何指定回合中檢查 Bot 的狀態。

我們在建立 Bot 快速入門中使用 Bot Framework v4 在本機建置的 EchoBot，示範如何偵錯和檢查 Bot 的訊息狀態。 您也可以 使用 IDE 或 對 Bot Framework 模擬器進行偵錯，但若要偵錯狀態，您必須將檢查中間件新增至 Bot。 檢查 Bot 範例適用於 C#、 JavaScript、 Java 和 Python。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Power Virtual Agents ，並閱讀 選擇正確的聊天機器人解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

必要條件

• Bot 中間件 和管理 狀態的知識
• 瞭解如何對 SDK 優先 Bot 進行偵錯，以及 使用模擬器測試及偵錯的知識
• Bot Framework 模擬器的安裝
• 安裝 ngrok （如果您想要偵錯 Azure 中設定為使用其他通道的 Bot）
• C#、JavaScript、Java 或 Python 的檢查 Bot 範例複本

將您的模擬器更新為最新版本

使用 Bot 檢查中間件來偵錯 Bot 之前，請將模擬器更新為 4.5 版或更新版本。 檢查最新版本的更新。

若要檢查模擬器的版本，請選取 [說明]，然後在功能表中選取 [關於]。 您會看到目前的模擬器版本。

更新 Bot 程式碼

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 檔案中的 Bot 類別。

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

在更新 Bot 的程式代碼之前，請在終端機中執行下列命令，將其套件更新為最新版本：

npm install --save botbuilder@latest

接著，您需要更新 JavaScript Bot 的程式代碼，如下所示。 您可以在這裡閱讀更多： 更新 Bot 的程式代碼 ，或參閱 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 檔案中的 Bot 類別。

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 來提供設定為 @Primary 的 BotFrameworkHttpAdapter，因此它會覆寫 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 檔案中的 Bot 類別。

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

在更新 Bot 的程式代碼之前，請在終端機中執行下列命令來安裝必要的 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 檔案中的 Bot 類別。

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

在本機測試 Bot

更新程式代碼之後，您可以在本機執行 Bot，並使用兩個模擬器來測試偵錯功能：一個用來傳送和接收訊息，另一個則用來檢查偵錯模式中的訊息狀態。 若要在本機測試 Bot：

1. 移至終端機中的 Bot 目錄，然後執行下列命令，在本機執行 Bot：

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. 開啟模擬器。 選取 [ 開啟 Bot]。 使用 和 MicrosoftAppId 和 MicrosoftAppPassword 值填入 Bot URL http://localhost:3978/api/messages。 如果您有 JavaScript Bot，您可以在 Bot 的 .env 檔案中找到這些值。 如果您有 C# Bot，您可以在 appsettings.json 檔案中找到這些值。 針對 Java Bot，您可以在 application.properties 檔案中找到這些值。 選取 Connect。

3. 現在開啟另一個模擬器視窗。 第二個模擬器視窗會以調試程式的形式運作。 依照上一個步驟中所述的指示操作。 核取 [以偵錯模式開啟]，然後選取 [連線]。

4. 此時，您會在偵錯模擬器中看到具有唯一標識碼 （/INSPECT attach <identifier>） 的命令。 使用偵錯模擬器中的標識碼複製整個命令，並將它貼到第一個模擬器的聊天方塊中。

   注意

   當您在 Bot 程式代碼中新增檢查中間件之後，每次以偵錯模式啟動模擬器時，都會產生唯一標識符。

5. 現在，您可以在第一個模擬器的聊天方塊中傳送訊息，並在偵錯模擬器中檢查訊息。 若要檢查訊息的狀態，請在偵錯模擬器中選取 [Bot 狀態]，並在右側 JSON 視窗中展開值。 您會在偵錯模擬器中看到 Bot 的狀態：

   

檢查在 Azure 中設定的 Bot 狀態

如果您想要檢查在 Azure 中設定的 Bot 狀態，並連線到頻道（例如 Teams），您必須安裝並執行 ngrok。

執行 ngrok

此時，您已將模擬器更新為最新版本，並在 Bot 的程式代碼中新增檢查中間件。 下一個步驟是執行 ngrok 並設定本機 Bot。 執行 ngrok 之前，您必須在本機執行 Bot。

若要在本機執行 Bot：

1. 移至終端機中的 Bot 資料夾，並將 npm 註冊設定為使用 最新的組建

2. 在本機執行 Bot。 您會看到 Bot 公開埠號碼，例如 3978。

3. 開啟另一個命令提示字元，並移至 Bot 的項目資料夾。 執行以下命令：

   ngrok http 3978
   

4. ngrok 現在已連線到本機執行中的 Bot。 複製安全 （HTTPS） 公用IP位址。

   

更新 Bot 資源

既然本機 Bot 已連線到 ngrok，您可以在 Azure 中設定 Bot 資源以使用 ngrok URL。

1. 移至 Azure 中的 Bot 資源。 在左側功能表上的 [設定] 底下，選取 [組態]。

   1. 將傳 訊端點 設定為您複製的 ngrok IP 位址。 如有必要，請在IP位址後面新增 /api/messages 。 例如： https://e58549b6.ngrok.io/api/messages 。

   2. 選取 [ 啟用串流端點]。

      

   3. 選取 [套用] 以儲存變更。

      提示

      如果未啟用 [套用]，您可以取消核取 [啟用串流端點]，然後選取 [套用]，然後核取 [啟用串流端點]，然後再次選取 [套用]。 您必須確定 已核取 [啟用串流端點 ]，並儲存端點的設定。

2. 移至 Bot 的資源群組。

   1. 選取 [ 部署]，然後選取先前成功部署的 Bot 資源。 從左側功能表中選取 [範本 ]， 以取得與 Bot 相關聯之 Web 應用程式的 MicrosoftAppId 和 MicrosoftAppPassword 。

      

   2. 使用 MicrosoftAppId 和 MicrosoftAppPassword 更新 Bot 的組態檔 （appsettings.json for C# 或 .env for JavaScript）。

3. 啟動模擬器，選取 [開啟 Bot]，然後在 Bot URL 中輸入 http://localhost:3978/api/messages 。 以您新增至 Bot 組態檔的相同 MicrosoftAppId 和 MicrosoftAppPassword 填入 Microsoft 應用程式識別碼和 Microsoft 應用程式密碼。 然後選取 [連線]。

4. 您執行中的 Bot 現在已連線到 Azure 中的 Bot 資源。 若要在 網路聊天 中測試 Azure 中的 Bot，請移至您的 Bot 資源，選取 [在 網路聊天 中測試]，然後將訊息傳送至 Bot。

啟用偵錯模式

1. 在模擬器中，選取 [偵錯]，然後選取 [開始偵錯]。

2. 輸入 Bot URL 的 ngrok IP 地址 （別忘了新增 /api/messages）（例如 ）。 https://e58549b6.ngrok.io/api/messages

   1. 針對 Microsoft 應用程式識別碼，輸入 Bot 的應用程式識別碼。
   2. 針對 Microsoft 應用程式密碼，輸入 Bot 的應用程式密碼。
   3. 也請確定 已核取 [以偵錯模式 開啟]。
   4. 選取 Connect。

3. 啟用偵錯模式后，模擬器會產生 UUID。 UUID 是每次在模擬器中啟動偵錯模式時所產生的唯一標識碼。

4. 將 UUID 複製並貼到頻道聊天方塊 網路聊天 聊天方塊中的 [測試]。 您會在聊天方塊中看到「附加至會話，所有流量正在復寫以進行檢查」訊息。

您可以在設定的頻道聊天方塊中傳送訊息，開始對 Bot 進行偵錯。 您的本機模擬器會自動更新訊息，其中包含偵錯的所有詳細數據。 若要檢查 Bot 的訊息狀態，請選取 [Bot 狀態 ]，然後展開 右側 JSON 視窗中的值 。

下一步

• 瞭解如何使用文字記錄檔案對 Bot 進行偵錯。
• 瞭解如何偵 錯技能或技能取用者。