Hinzufügen von Ablaufverfolgungsaktivitäten zu Ihrem BotAdd trace activities to your bot

gilt für: SDK v4APPLIES TO: SDK v4

Eine Ablaufverfolgungsaktivität ist eine Aktivität, die von Ihrem Bot an den Bot Framework Emulator gesendet werden kann.A trace activity is an activity that your bot can send to the Bot Framework Emulator. Sie können Ablaufverfolgungsaktivitäten verwenden, um einen Bot interaktiv zu debuggen, da diese Ihnen das Anzeigen von Informationen zu Ihrem Bot während der lokalen Ausführung ermöglichen.You can use trace activities to interactively debug a bot, as they allow you to view information about your bot while it runs locally.

Ablaufverfolgungsaktivitäten werden nur an den Emulator und nicht an andere Clients oder Kanäle gesendet.Trace activities are sent only to the Emulator and not to any other client or channel. Vom Emulator werden sie im Protokoll angezeigt, aber nicht im Hauptbereich des Chats.The Emulator displays them in the log but not the main chat panel.

  • Ablaufverfolgungsaktivitäten, die über den Turn-Kontext gesendet werden, fließen über die SendActivity-Handler, die für den Turn-Kontext registriert wurden.Trace activities sent via the turn context are sent through the send activity handlers registered on the turn context.
  • Über den Turn-Kontext gesendete Ablaufverfolgungsaktivitäten werden der eingehenden Aktivität zugeordnet, indem der Konversationsverweis angewendet wird, falls vorhanden.Trace activities sent via the turn context are associated with the inbound activity, by applying the conversation reference, if there was one. Bei einer proaktiven Nachricht handelt es sich bei der ReplyTo-ID um eine neue GUID.For a proactive message, the reply to ID will be a new GUID.
  • Unabhängig von der Art des Sendevorgangs wird für eine Ablaufverfolgungsaktivität niemals das Flag responded (Beantwortet) festgelegt.Regardless of how it is sent, a trace activity never sets the responded flag.

Verwenden einer AblaufverfolgungsaktivitätTo use a trace activity

Zum Anzeigen einer Ablaufverfolgungsaktivität im Emulator benötigen Sie ein Szenario, bei dem Ihr Bot eine Ablaufverfolgungsaktivität sendet, z. B. zum Auslösen einer Ausnahme und Senden einer Ablaufverfolgungsaktivität über den onTurnError-Handler des Adapters.In order to see a trace activity in the Emulator, you need a scenario in which your bot will send a trace activity, such as throwing an exception and sending a trace activity from the adapter's on turn error handler.

Gehen Sie beim Senden einer Ablaufverfolgungsaktivität von Ihrem Bot wie folgt vor:To send a trace activity from your bot:

  1. Erstellen Sie eine neue Aktivität.Create a new activity.
    • Legen Sie die zugehörige type-Eigenschaft auf „trace“ fest.Set its type property to "trace". Dies ist erforderlich.This is required.
    • Legen Sie optional die Eigenschaften name, label, value und value type so fest, wie dies für die Ablaufverfolgung geeignet ist.Optionally set its name, label, value, and value type properties, as appropriate for the trace.
  2. Verwenden Sie die SendActivity-Methode des Turn-Kontext-Objekts, um die Ablaufverfolgungsaktivität zu senden.Use the turn context object's send activity method to send the trace activity.
    • Mit dieser Methode werden Werte für die verbleibenden erforderlichen Eigenschaften der Aktivität basierend auf der eingehenden Aktivität hinzugefügt.This method adds values for the remaining required properties of the activity, based on the incoming activity. Hierzu gehören die Eigenschaften channel ID, service URL, from und recipient.These include the channel ID, service URL, from, and recipient properties.

Zeigen Sie eine Ablaufverfolgungsaktivität im Emulator wie folgt an:To view a trace activity in the Emulator:

  1. Führen Sie den Bot lokal auf Ihrem Computer aus.Run the bot locally on your machine.
  2. Testen Sie ihn mit dem Emulator.Test it using the Emulator.
    • Interagieren Sie mit dem Bot, und verwenden Sie die Schritte in Ihrem Szenario, um die Ablaufverfolgungsaktivität zu generieren.Interact with the bot and use the steps in your scenario to generate the trace activity.
    • Wenn Ihr Bot die Ablaufverfolgungsaktivität ausgibt, wird sie im Emulatorprotokoll angezeigt.When your bot emits the trace activity, the trace activity is displayed in the Emulator log.

Hier ist eine Ablaufverfolgungsaktivität angegeben, die ggf. im folgenden Fall angezeigt wird: Sie führen den „Core Bot“ aus, ohne zuerst die QnAMaker-Wissensdatenbank einzurichten, die vom Bot verwendet wird.Here is a trace activity you might see if you ran the Core bot without first setting up the QnAMaker knowledge base that the bot relies upon.

Screenshot: Emulator

Hinzufügen einer Ablaufverfolgungsaktivität zum OnError-Handler des AdaptersAdd a trace activity to the adapter's on-error handler

Der onTurnError-Handler fängt alle Ausnahmen ab, die vom Bot während eines Turns ausgelöst und nicht anderweitig abgefangen werden.The adapter's on turn error handler catches any otherwise uncaught exception thrown from the bot during a turn. Dies ist ein guter Ort für eine Ablaufverfolgungsaktivität, da Sie eine benutzerfreundliche Nachricht an den Benutzer und Debuginformationen zur Ausnahme an den Emulator senden können.This is a good place for a trace activity, as you can send a user-friendly message to the user and send debugging information about the exception to the Emulator.

Dieser Beispielcode stammt aus dem Beispiel Core Bot.This example code is from the Core Bot sample. Das vollständige Beispiel finden Sie unter C#, JavaScript oder Python.See the complete sample in C# or JavaScript or Python. Für Java ist der folgende Code aus dem SDK-Code Java .For Java the code below is from the SDK code Java.

Mit dem OnTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeinformationen einzufügen, und an den Emulator gesendet.The adapter's OnTurnError handler creates the trace activity to include the exception information and sends it to the Emulator.

AdapterWithErrorHandler.csAdapterWithErrorHandler.cs

OnTurnError = async (turnContext, exception) =>
{
    // 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");
};

Zusätzliche RessourcenAdditional resources