次の方法で共有


ボットへのトレース アクティビティの追加

この記事の対象: SDK v4

トレース アクティビティ は、ボットが Bot Framework Emulator に送信できるアクティビティです。 トレース アクティビティを使用すると、ボットをローカルで実行している間に情報を表示することができるため、ボットをインタラクティブにデバッグできます。

トレース アクティビティはエミュレーターにのみ送信され、他のクライアントまたはチャネルには送信されません。 エミュレーターでは、メインのチャット パネルではなく、ログに表示されます。

  • ターン コンテキストを介して送信されたトレース アクティビティは、ターン コンテキストに登録された送信アクティビティ ハンドラーを介して送信されます。
  • ターン コンテキストを介して送信されたトレース アクティビティは、会話リファレンスがあった場合にそれを適用し、受信アクティビティに関連付けられています。 プロアクティブ メッセージの場合、[reply to ID]\(返信先 ID) は新しい GUID になります。
  • トレース アクティビティでは、送信方法に関係なく、[responded] フラグが設定されることはありません。

Note

Bot Framework JavaScript SDK、C#、Python SDK は引き続きサポートされますが、Java SDK については、最終的な長期サポートは 2023 年 11 月に終了する予定です。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットを構築する場合は、Microsoft Copilot Studio の使用をご検討ください。また、適切なコパイロット ソリューションの選択に関する記事もお読みください。

詳細については、「The future of bot building」をご覧ください。

トレース アクティビティを使用するには

エミュレーターでトレース アクティビティを表示するには、例外をスローし、アダプターのオン ターン エラー ハンドラーからトレース アクティビティを送信するなど、ボットがトレース アクティビティを送信するシナリオが必要です。

ボットからトレース アクティビティを送信するには:

  1. 新しいアクティビティを作成します。
    • 必須の type プロパティを "trace" に設定します。
    • 必要に応じて、トレースに対応する、namelabelvalue、および value type プロパティを設定します。
  2. turn context オブジェクトの send activity メソッドを使用して、トレース アクティビティを送信します。
    • このメソッドは、受信アクティビティに基づいて、アクティビティの残りの必須プロパティの値を追加します。 これらのプロパティには、channel IDservice URLfrom、および recipient プロパティが含まれます。

エミュレーターでトレース アクティビティを表示するには:

  1. お使いのマシン上でローカルでボットを実行します。
  2. エミュレーターを使ってテストします。
    • ボットと対話し、シナリオのステップを使用してトレース アクティビティを生成します。
    • ボットがトレース アクティビティを出力すると、トレース アクティビティがエミュレーター ログに表示されます。

ここでは、ボットが依存している QnAMaker ナレッジ ベースを最初に設定することなく、コアボットを実行した場合に表示されるトレース アクティビティを示します。

Emulator でのトレース アクティビティの出力のスクリーンショット。

アダプターのオンエラー ハンドラーにトレース アクティビティを追加する

アダプターの オン ターン エラー ハンドラーは、ターン中にボットからスローされ、その他の方法ではキャッチされない例外をキャッチします。 エラー ハンドラーは、わかりやすいメッセージをユーザーに送信し、例外に関するデバッグ情報を Emulator に送信できるため、トレース アクティビティに適しています。

このコード例は、コア ボット サンプルからのものです。 C#JavaScriptPython、または Java の完全なサンプルをご覧ください。

アダプターの 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");
    };
}

次のステップ