通过

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

将跟踪活动添加到机器人

  • 项目

适用于：SDK v4

跟踪活动是机器人可发送到 Bot Framework Emulator 的活动。 可以使用跟踪活动来以交互方式调试机器人，因为这些活动允许在本地运行机器人时查看有关机器人的信息。

跟踪活动只发送到 Emulator，而不会发送到任何其他客户端或通道。 Emulator 将跟踪活动显示在日志中，但不会显示在主聊天面板中。

  • 通过轮次上下文发送的跟踪活动将通过轮次上下文中注册的发送活动处理程序发送。
  • 通过轮次上下文发送的跟踪活动与入站活动相关联，关联方式是应用聊天引用（如果有）。 对于主动消息，“接收方 ID”将是新的 GUID。
  • 无论发送方式如何，跟踪活动永远都不会设置 responded 标志。

注意

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

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

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

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

使用跟踪活动

若要在 Emulator 中查看跟踪活动，需要制定一个方案，机器人将在其中发送一个跟踪活动，例如，引发异常，并从适配器的轮次错误处理程序发送跟踪活动。

若要从机器人发送跟踪活动：

  1. 创建一个新活动。
    • 将其必需的 type 属性设置为“trace”。
    • （可选）为该活动设置适用于跟踪的 name、label、value 和 value type 属性。
  2. 使用轮次上下文对象的 send activity 方法发送跟踪活动。
    • 此方法根据传入的活动，为该活动的剩余必需属性添加值。 这些属性包括 channel ID、service URL、from 和 recipient。

若要在 Emulator 中查看跟踪活动：

  1. 在计算机本地运行机器人。
  2. 使用 Emulator 测试机器人。
    • 与机器人交互，并使用方案中的步骤生成跟踪活动。
    • 当机器人发出跟踪活动时，跟踪活动将显示在 Emulator 日志中。

下面是在未事先设置机器人所依赖的 QnAMaker 知识库的情况下运行核心机器人时可能会看到的跟踪活动。

Emulator 中跟踪活动输出的屏幕截图。

将跟踪活动添加到适配器的出错处理程序

适配器的轮次错误处理程序捕获机器人在执行某个轮次过程中引发的任何未捕获到的异常。 错误处理程序是非常适合跟踪活动的位置，因为这样可以向用户发送用户友好的消息，并将有关异常的调试信息发送给 Emulator。

此示例代码摘自核心机器人示例。 请参阅完整的 C#、JavaScript、Python 或 Java 示例。

适配器的 OnTurnError 处理程序创建跟踪活动以包含异常信息，并将其发送到 Emulator。

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

后续步骤