將追蹤活動新增至 Bot

適用於： SDK v4

追蹤活動是 Bot 可以傳送至 Bot Framework 模擬器的活動。 您可以使用追蹤活動對 Bot 進行互動式偵錯，因為這些活動可讓您檢視 Bot 在本機執行時的資訊。

追蹤活動只會傳送至模擬器，而不是傳送至任何其他用戶端或通道。 模擬器會在記錄中顯示它們，但不會顯示主要聊天面板。

• 透過回合內容傳送的追蹤活動會透過 在回合內容上註冊的傳送活動處理程式 傳送。
• 透過回合內容傳送的追蹤活動會藉由套用交談參考來與輸入活動相關聯，如果有的話。 對於主動式訊息，標識碼 的回復 將會是新的 GUID。
• 不論其傳送方式為何，追蹤活動永遠不會設定響應的旗標。

注意

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

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

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀 選擇正確的 Copilot 解決方案。

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

使用追蹤活動

若要在模擬器中查看追蹤活動，您需要 Bot 傳送追蹤活動的案例，例如擲回例外狀況，以及從適配卡的開啟錯誤處理程式傳送追蹤活動。

若要從 Bot 傳送追蹤活動：

1. 建立新的活動。
   • 將其必要的 類型 屬性設定為 「trace」。
   • 或者，視追蹤情況設定其名稱、標籤、值和實值類型屬性。
2. 使用回合內容對象的傳送活動方法來傳送追蹤活動。
   • 這個方法會根據傳入活動，為活動的其餘必要屬性新增值。 這些屬性包括 頻道標識碼、 服務 URL、 來自 和 收件者 屬性。

若要在模擬器中檢視追蹤活動：

1. 在本機電腦上執行 Bot。
2. 使用模擬器進行測試。
   • 與 Bot 互動，並使用案例中的步驟來產生追蹤活動。
   • 當 Bot 發出追蹤活動時，追蹤活動會顯示在模擬器記錄中。

以下是追蹤活動，您可能會看到您是否執行 Core Bot，而不需要先設定 Bot 所依賴的 QnAMaker 知識庫。

將追蹤活動新增至適配卡的錯誤處理程式

適配卡 的開啟錯誤 處理程式會攔截在回合期間從 Bot 擲回的任何其他未攔截例外狀況。 錯誤處理程式是追蹤活動的良好位置，因為您可以將易記訊息傳送給使用者，並將例外狀況的偵錯資訊傳送給模擬器。

此範例程式代碼來自 Core Bot 範例。 請參閱 C#、JavaScript、Python 或 Java 的完整範例。

C#

配接器的 OnTurnError 處理程式會建立追蹤活動，以包含例外狀況資訊，並將其傳送至模擬器。

AdapterWithErrorHandler.cs

    {
        // Log any leaked exception from the application.
        // NOTE: In production environment, you should consider logging this to
        // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
        // to add telemetry capture to your bot.
        logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        if (conversationState != null)
        {
            try
            {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
                await conversationState.DeleteAsync(turnContext);
            }
            catch (Exception e)
            {
                logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
            }
        }

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

JavaScript

配接器的 onTurnError 處理程式會建立追蹤活動，以包含例外狀況資訊，並將其傳送至模擬器。

index.js

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    let onTurnErrorMessage = 'The bot encountered an error or bug.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    // Clear out state
    await conversationState.delete(context);
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Define a state store for your bot. See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
// A bot requires a state store to persist the dialog and user state between messages.

// For local development, in-memory storage is used.

Java

在 Java SDK 中，AdapterWithErrorHandler類別會包含在 com.microsoft.bot.integration 套件中的 SDK 中。 配接器的 onTurnError 處理程式會建立追蹤活動，以包含例外狀況資訊，並將其傳送至模擬器。 默認配接器的原始程式碼如下所示。

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a
                // Web pages.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

配接器的 on_error 處理程式會建立追蹤活動，以包含例外狀況資訊，並將其傳送至模擬器。

adapter_with_error_handler.py

# This check writes out errors to console log
# NOTE: In production environment, you should consider logging this to Azure
#       application insights.
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
traceback.print_exc()

# Send a message to the user
await context.send_activity("The bot encountered an error or bug.")
await context.send_activity(
    "To continue to run this bot, please fix the bot source code."
)
# Send a trace activity if we're talking to the Bot Framework Emulator
if context.activity.channel_id == "emulator":
    # Create a trace activity that contains the error object
    trace_activity = Activity(
        label="TurnError",
        name="on_turn_error Trace",
        timestamp=datetime.utcnow(),
        type=ActivityTypes.trace,
        value=f"{error}",
        value_type="https://www.botframework.com/schemas/error",
    )
    # Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.send_activity(trace_activity)

下一步

• 如何使用 檢查中間件 偵錯 Bot 說明如何新增會發出追蹤活動的中間件。
• 若要偵錯已部署的 Bot，您可以使用 Application Insights。 如需詳細資訊，請參閱 將遙測新增至 Bot。
• 如需每個活動類型的詳細資訊，請參閱 Bot Framework 活動架構。