Debuggen eines Bots mit Inspektions-Middleware

GILT FÜR: SDK v4

In diesem Artikel wird beschrieben, wie Sie Ihren Bot mit Inspektions-Middleware debuggen. Diese Funktion ermöglicht es dem Bot Framework Emulator, den Datenverkehr in und aus dem Bot zu debuggen und den aktuellen Status des Bots zu überprüfen. Sie können eine Ablaufverfolgungsnachricht verwenden, um Daten an den Emulator zu senden und den Status Ihres Bots dann zu jedem Zeitpunkt der Konversation untersuchen.

Wir verwenden eine EchoBot-Instanz, die lokal mit Bot Framework v4 im Einen Bot erstellen-Schnellstarter erstellt wurde, um das Debuggen und Überprüfen des Nachrichtenstatus eines Bots zu veranschaulichen. Sie können auch die Schritte unter Debuggen eines Bots mithilfe von IDE oder Debuggen mit dem Bot Framework Emulator ausführen, aber zum Debuggen des Status müssen Sie Ihrem Bot Inspektions-Middleware hinzufügen. Die Inspektions-Bot-Beispiele sind für C#, JavaScript, Java und Python verfügbar.

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. Es werden nur kritische Sicherheits- und Programmfehlerbehebungen innerhalb dieses Repositorys durchgeführt.

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-Design.

Voraussetzungen

Update Ihres Emulators auf die aktuellste Version

Bevor Sie die Middleware zur Inspektion von Bots für Ihren Bot einsetzen, müssen Sie Ihren Emulator auf Version 4.5 oder höher aktualisieren. Informieren Sie sich über die aktuellen Updateversionen.

Wählen Sie im Menü Hilfe, dann Über, um die Version Ihres Emulators zu überprüfen. Die aktuelle Version Ihres Emulators wird angezeigt.

Aktualisieren Ihres Botcodes

Der Inspektionsstatus und die Inspektions-Middleware werden in der Datei Startup.cs konfiguriert und dann vom Adapter verwendet.

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

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

Aktualisieren Sie die Botklasse in der Datei EchoBot.cs.

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

Lokales Testen Ihres Bots

Nach dem Aktualisieren des Codes können Sie Ihren Bot lokal ausführen und das Debugging-Feature mit zwei Emulatoren testen: einer zum Senden und Empfangen von Nachrichten und einen zum Untersuchen des Status von Nachrichten im Debugmodus. Um Ihren Bots lokal zu testen:

  1. Navigieren Sie in einem Terminal zum Verzeichnis Ihres Bots, und verwenden Sie den folgenden Befehl, um Ihren Bot lokal auszuführen:

    dotnet run
    
  2. Öffnen Sie Ihren Emulator. Wählen Sie Bot öffnen aus. Geben Sie die Bot-URL als http://localhost:3978/api/messages und die Werte für MicrosoftAppId und MicrosoftAppPassword an. Wenn Sie über einen JavaScript-Bot verfügen, finden Sie diese Werte in der .env-Datei Ihres Bots. Falls Sie einen C#-Bot nutzen, finden Sie diese Werte in der Datei appsettings.json. Für einen Java-Bot finden Sie diese Werte in der Datei application.properties. Wählen Sie Verbinden aus.

  3. Öffnen Sie nun ein weiteres Emulator-Fenster. Dieses zweite Emulator-Fenster wird als Debugger genutzt. Befolgen Sie die Anleitung aus dem vorherigen Schritt. Aktivieren Sie die Option Im Debugging-Modus öffnen und klicken Sie auf Verbinden.

  4. An diesem Punkt wird ein Befehl mit einem eindeutigen Bezeichner (/INSPECT attach <identifier>) in Ihrem Debugging-Emulator angezeigt. Kopieren Sie den gesamten Befehl mit dem Bezeichner aus dem Debugemulator, und fügen Sie ihn in das Chatfeld des ersten Emulators ein.

    Hinweis

    Ein eindeutiger Bezeichner wird jedes Mal generiert, wenn der Emulator im Debugmodus gestartet wird, nachdem Sie die Inspektions-Middleware im Code Ihres Bots hinzugefügt haben.

  5. Jetzt können Sie im Chatfeld Ihres ersten Emulators Nachrichten senden und diese im Debugging-Emulator untersuchen. Klicken Sie zum Untersuchen des Status der Nachrichten im Debugging-Emulator auf Botzustand und erweitern Sie im rechten JSON-Fenster die Option Werte. Im Debugging-Emulator wird der Status des Bots angezeigt:

    bot state

Untersuchen des Zustands eines in Azure konfigurierten Bots

Wenn Sie den Zustand Ihres in Azure konfigurierten Bots mit Kanalverbindungen (z. B. Teams) untersuchen möchten, müssen Sie ngrok installieren und ausführen.

Ausführen von ngrok

Sie haben Ihren Emulator jetzt auf die aktuelle Version aktualisiert und die Inspektions-Middleware im Code Ihres Bots hinzugefügt. Als nächstes führen Sie ngrok aus und konfigurieren Sie Ihren lokalen Bot. Vor der ngrok-Ausführung müssen Sie Ihren Bot lokal ausführen.

Um Ihren Bot lokal auszuführen:

  1. Gehen Sie in einem Terminal zum Ordner Ihres Bots, und legen Sie für Ihre npm-Registrierung fest, dass die aktuellen Builds verwendet werden sollen

  2. Führen Sie Ihren Bot lokal aus. Sie sehen, dass von Ihrem Bot eine Portnummer wie 3978 verfügbar gemacht wird.

  3. Öffnen Sie eine weitere Eingabeaufforderung, und gehen Sie zum Projektordner Ihres Bots. Führen Sie den folgenden Befehl aus:

    ngrok http 3978
    
  4. ngrok ist jetzt mit Ihrem lokal ausgeführten Bot verbunden. Kopieren Sie die sichere (HTTPS) öffentliche IP-Adresse.

    ngrok success

Aktualisieren Sie Ihre Bot-Ressource

Wenn Ihr lokaler Bot mit ngrok verbunden ist, können Sie Ihre Bot-Ressource in Azure so konfigurieren, dass sie die ngrok-URL verwendet.

  1. Wechseln Sie zu Ihrer Bot-Ressource in Azure. Wählen Sie im linken Menü unterEinstellungen die Option Konfiguration.

    1. Legen Sie den Messaging-Endpunkt auf die ngrok-IP-Adresse fest, die Sie kopiert haben. Fügen Sie bei Bedarf nach der IP-Adresse /api/messages hinzu. Beispielsweise https://e58549b6.ngrok.io/api/messages.

    2. Wählen Sie Streamingendpunkt aktivieren.

      Set endpoint

    3. Wählen Sie Übernehmen aus, um die Änderungen zu speichern.

      Tipp

      Wenn Anwenden nicht aktiviert ist, können Sie die Option Streamingendpunkt aktivieren deaktivieren und auf Anwenden klicken. Aktivieren Sie anschließend die Option Streamingendpunkt aktivieren wieder und klicken Sie erneut auf Anwenden. Sie müssen sicherstellen, dass die Option Enable Streaming Endpoint (Streamingendpunkt aktivieren) aktiviert ist und die Konfiguration des Endpunkts gespeichert wird.

  2. Wechseln Sie zu Ihrer Bot-Ressourcengruppe.

    1. Wählen Sie Bereitstellung und dann die Bot-Ressource aus, die zuvor erfolgreich bereitgestellt wurde. Wählen Sieim linken Menü Vorlage aus, um die MicrosoftAppId und das MicrosoftAppPassword für die Web-App abzurufen, die Ihrem Bot zugeordnet ist.

      Get inputs

    2. Aktualisieren Sie die Konfigurationsdatei Ihres Bots (appsettings.json für C# oder .env für JavaScript) mit der MicrosoftAppId und dem MicrosoftAppPassword.

  3. Starten Sie Ihren Emulator, klicken Sie auf Bot öffnen und geben Sie http://localhost:3978/api/messages unter Bot-URL ein. Füllen Sie die Microsoft App-ID und das Microsoft App-Passwort mit derselben MicrosoftAppId und MicrosoftAppPassword aus, die Sie zur Konfigurationsdatei unseres Bots hinzugefügt haben. Wählen Sie dann Verbinden aus.

  4. Ihr ausgeführter Bot ist jetzt mit Ihrer Bot-Ressource in Azure verbunden. Um Ihren Bot in Azure in Webchat zu testen, gehen Sie zu Ihren Bot-Ressourcen, wählen Sie In Webchat testen und senden Sie Nachrichten an Ihren Bot.

Aktivieren Sie den Debugmodus:

  1. Wählen Sie im Emulator die Option Debuggen, dann Debugging starten.

  2. Fügen Sie die ngrok-IP-Adresse (Zusatz /api/messages nicht vergessen) unter Bot-URL ein (z. B. https://e58549b6.ngrok.io/api/messages).

    1. Geben Sie als Microsoft App-ID die App-ID Ihres Bots ein.
    2. Geben Sie als Microsoft App-Kennwort den geheimen App-Schlüssel Ihres Bots ein.
    3. Stellen Sie sicher, dass auch die Option Im Debugmodus öffnen aktiviert ist.
    4. Wählen Sie Verbinden aus.
  3. Wenn der Debugmodus aktiviert ist, generiert der Emulator eine UUID. Ein UUID ist eine eindeutige ID, die bei jedem Start des Debugmodus in Ihrem Emulator generiert wird.

  4. Kopieren Sie die UUID und fügen Sie sie in das Chatfeld von In Webchat testen oder das Chatfeld Ihres Kanals ein. Im Chatfeld wird die Nachricht „An Sitzung angefügt, der gesamte Datenverkehr wird für die Untersuchung repliziert“ angezeigt.

Sie können mit dem Debuggen des Bots beginnen, indem Sie im Chatfeld des konfigurierten Kanals Nachrichten senden. Ihr lokaler Emulator aktualisiert die Nachrichten automatisch mit allen Details für das Debuggen. Klicken Sie zum Untersuchen des Nachrichtenstatus Ihres Bots auf Bot-Status und erweitern Sie im JSON-Fenster auf der rechten Seite die Option Werte.

debug-inspection-middleware

Nächste Schritte