Hinzufügen von Ablaufverfolgungsaktivitäten zu Ihrem Bot

GILT FÜR: SDK v4

Eine Ablaufverfolgungsaktivität ist eine Aktivität, die von Ihrem Bot an den Bot Framework Emulator gesendet werden kann. 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.

Ablaufverfolgungsaktivitäten werden nur an den Emulator und nicht an andere Clients oder Kanäle gesendet. Vom Emulator werden sie im Protokoll angezeigt, aber nicht im Hauptbereich des Chats.

• Ablaufverfolgungsaktivitäten, die über den Turn-Kontext gesendet werden, fließen über die SendActivity-Handler, die für den Turn-Kontext registriert wurden.
• Über den Turn-Kontext gesendete Ablaufverfolgungsaktivitäten werden der eingehenden Aktivität zugeordnet, indem der Konversationsverweis angewendet wird, falls vorhanden. Bei einer proaktiven Nachricht handelt es sich bei der ReplyTo-ID um eine neue GUID.
• Unabhängig von der Art des Sendevorgangs wird für eine Ablaufverfolgungsaktivität niemals das Flag responded (Beantwortet) festgelegt.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Wenn Sie einen neuen Bot erstellen möchten, sollten Sie den Einsatz von Power Virtual Agents in Betracht ziehen und sich über die Auswahl der richtigen Chatbot-Lösung informieren.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Buildings.

Verwenden einer Ablaufverfolgungsaktivität

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.

Gehen Sie beim Senden einer Ablaufverfolgungsaktivität von Ihrem Bot wie folgt vor:

1. Erstellen Sie eine neue Aktivität.
   • Legen Sie die benötigte type-Eigenschaft auf „trace“ fest.
   • Legen Sie optional die Eigenschaften name, label, value und value type so fest, wie dies für die Ablaufverfolgung geeignet ist.
2. Verwenden Sie die SendActivity-Methode des Turn-Kontext-Objekts, um die Ablaufverfolgungsaktivität zu senden.
   • Mit dieser Methode werden Werte für die verbleibenden erforderlichen Eigenschaften der Aktivität basierend auf der eingehenden Aktivität hinzugefügt. Hierzu gehören die Eigenschaften channel ID, service URL, from und recipient.

Zeigen Sie eine Ablaufverfolgungsaktivität im Emulator wie folgt an:

1. Führen Sie den Bot lokal auf Ihrem Computer aus.
2. Testen Sie ihn mit dem Emulator.
   • Interagieren Sie mit dem Bot, und verwenden Sie die Schritte in Ihrem Szenario, um die Ablaufverfolgungsaktivität zu generieren.
   • Wenn Ihr Bot die Ablaufverfolgungsaktivität ausgibt, wird sie im Emulatorprotokoll angezeigt.

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.

Hinzufügen einer Ablaufverfolgungsaktivität zum OnError-Handler des Adapters

Der onTurnError-Handler fängt alle Ausnahmen ab, die vom Bot während eines Turns ausgelöst und nicht anderweitig abgefangen werden. Der Fehler-Handler 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.

Dieser Beispielcode stammt aus dem BeispielCore Bot. Das vollständige Beispiel finden Sie unter C#, JavaScript, Python oder Java.

C#

Mit dem OnTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeinformationen einzufügen, und an den Emulator gesendet.

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

Mit dem onTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden.

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

Im Java SDK ist eine AdapterWithErrorHandler-Klasse als Teil des SDK im Paket com.microsoft.bot.integration enthalten. Mit dem onTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden. Der Quellcode für den Standardadapter wird unten angezeigt.

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

Mit dem on_error-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden.

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)

Nächste Schritte

• Unter Debuggen eines Bots mit Middleware zur Überprüfung wird beschrieben, wie Sie Middleware zum Ausgeben von Ablaufverfolgungsaktivitäten hinzufügen.
• Zum Debuggen eines bereitgestellten Bots können Sie Application Insights verwenden. Weitere Informationen finden Sie unter Hinzufügen von Telemetriefunktionen zu Ihrem Bot.
• Ausführliche Informationen zu den einzelnen Aktivitätstypen finden Sie unter Bot Framework-Aktivitätsschema.