Debuggen eines Bots mit Middleware zur Überprüfung

GILT FÜR: SDK v4

In diesem Artikel wird beschrieben, wie Sie einen Bot mithilfe von Inspektions-Middleware debuggen. Dieses Feature ermöglicht es dem Bot Framework Emulator, Datenverkehr in und aus dem Bot zu debuggen und den aktuellen Zustand des Bots anzuzeigen. Sie können eine Ablaufverfolgungsnachricht verwenden, um Daten an den Emulator zu senden und dann den Zustand Ihres Bots in jeder beliebigen Wendung der Unterhaltung zu überprüfen.

Wir verwenden einen EchoBot, der lokal mit Bot Framework v4 Erstellen eines Bots erstellt wurde, um zu zeigen, wie der Nachrichtenstatus des Bots debuggen und überprüfen kann. 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 Zustands müssen Sie Ihrem Bot Middleware zur Überprüfung hinzufügen. Die Beispiele für Den Inspektionsbot sind für C#, JavaScript, Java und Python verfügbar.

Hinweis

Die Bot Framework-Python- und Java-SDKs werden eingestellt und der endgültige langfristige Support endet im November 2023. Es werden nur kritische Sicherheits- und Fehlerbehebungen innerhalb dieses Repositorys durchgeführt. Vorhandene Bots, die mit diesen SDKs erstellt wurden, funktionieren weiterhin.

Erwägen Sie für die Entwicklung neuer Bots die Verwendung von Power Virtual Agents. Weitere Informationen finden Sie unter Die Zukunft des Botaufbaus.

Voraussetzungen

Aktualisieren Ihres Emulators auf die neueste Version

Bevor Sie die Middleware für die Botüberprüfung zum Debuggen Ihres Bots verwenden, aktualisieren Sie Ihren Emulator auf Version 4.5 oder höher. Informieren Sie sich über die aktuellen Updateversionen.

Um die Version Ihres Emulators zu überprüfen, wählen Sie Hilfe und dann Info im Menü aus. Sie sehen die aktuelle Version Ihres Emulators.

aktuelle Version

Aktualisieren Ihres Botcodes

Richten Sie die Untersuchung des Zustands ein, und fügen Sie die Middleware zur Überprüfung dem Adapter in der Datei Startup.cs hinzu. Die Untersuchung des Zustands wird per Abhängigkeitsinjektion bereitgestellt. Sehen Sie sich das Codeupdate unten an, oder lesen Sie das Prüf-Middlewarebeispiel auf GitHub.

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 die Debugfunktion mit zwei Emulatoren testen: einen zum Senden und Empfangen von Nachrichten und zum anderen, um den Status von Nachrichten im Debugmodus zu überprüfen. Führen Sie die folgenden Schritte aus, um Ihren Bot lokal zu testen:

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

    dotnet run
    
  2. Öffnen Sie Ihren Emulator. Wählen Sie Bot öffnen aus. Geben Sie die Bot-URL mit http://localhost:3978/api/messages den Werten MicrosoftAppId und MicrosoftAppPassword ein. Wenn Sie über einen JavaScript-Bot verfügen, finden Sie diese Werte in der env-Datei Ihres Bots. Wenn Sie über einen C#-Bot verfügen, 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.

  3. Öffnen Sie nun ein weiteres Emulatorfenster. Dieses zweite Emulatorfenster funktioniert als Debugger. Befolgen Sie die Anleitung aus dem vorherigen Schritt. Aktivieren Sie Im Debugmodus öffnen , und wählen Sie dann Verbinden aus.

  4. An diesem Punkt wird in Ihrem Debugemulator ein Befehl mit einem eindeutigen Bezeichner (/INSPECT attach <identifier>) 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 Überprüfungs-Middleware im Code Ihres Bots hinzugefügt haben.

  5. Jetzt können Sie Nachrichten im Chatfeld Ihres ersten Emulators senden und die Nachrichten im Debugemulator überprüfen. Um den Status der Nachrichten zu überprüfen, wählen Sie Botstatus im Debugemulator aus, und entfalten Sie die Werte im rechten JSON-Fenster . Der Status Ihres Bots wird im Debug-Emulator angezeigt:

    Botzustand

Untersuchen des Zustands eines in Azure konfigurierten Bots

Wenn Sie den Zustand Ihres bots überprüfen möchten, der in Azure konfiguriert und mit Kanälen (z. B. Teams) verbunden ist, müssen Sie ngrok installieren und ausführen.

Ausführen von ngrok

An diesem Punkt haben Sie Ihren Emulator auf die neueste Version aktualisiert und die Überprüfungs-Middleware im Code Ihres Bots hinzugefügt. Der nächste Schritt besteht darin, ngrok auszuführen und Ihren lokalen Bot zu konfigurieren. Vor der ngrok-Ausführung müssen Sie Ihren Bot lokal ausführen.

Gehen Sie wie folgt vor, um Ihren Bot lokal auszuführen:

  1. Wechseln Sie zum Ordner Ihres Bots in einem Terminal, und legen Sie Ihre npm-Registrierung so fest, dass sie die neuesten Builds verwendet.

  2. Führen Sie Ihren Bot lokal aus. Sie sehen, dass Ihr Bot eine Portnummer wie 3978verfügbar macht.

  3. Öffnen Sie eine weitere Eingabeaufforderung, und wechseln 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 öffentliche IP-Adresse (HTTPS).

    ngrok erfolg

Aktualisieren Ihrer Botressource

Nachdem Ihr lokaler Bot mit ngrok verbunden ist, können Sie Ihre Botressource in Azure für die Verwendung der ngrok-URL konfigurieren.

  1. Navigieren Sie zu Ihrer Botressource in Azure. Wählen Sie im linken Menü unter Einstellungen die Option Konfiguration aus.

    1. Legen Sie den Messagingendpunkt auf die kopierte ngrok-IP-Adresse fest. Fügen Sie bei Bedarf nach der IP-Adresse /api/messages hinzu. Beispiel: https://e58549b6.ngrok.io/api/messages.

    2. Wählen Sie Streamingendpunkt aktivieren aus.

      Festlegen des Endpunkts

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

      Tipp

      Wenn Anwenden nicht aktiviert ist, können Sie Streamingendpunkt aktivieren deaktivieren und Anwenden auswählen, dann Streamingendpunkt aktivieren und erneut Anwenden auswählen. Sie müssen sicherstellen, dass die Option Enable Streaming Endpoint (Streamingendpunkt aktivieren) aktiviert ist und die Konfiguration des Endpunkts gespeichert wird.

  2. Wechseln Sie zur Ressourcengruppe Ihres Bots.

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

      Abrufen von Eingaben

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

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

  4. Ihr ausgeführter Bot ist jetzt mit Ihrer Botressource in Azure verbunden. Um Ihren Bot in Azure in Webchat zu testen, wechseln Sie zu Ihren Botressourcen, wählen Sie Test in Webchat aus, und senden Sie Nachrichten an Ihren Bot.

Aktivieren des Debugmodus

  1. Wählen Sie in Ihrem Emulator Debuggen und dann Debuggen starten aus.

  2. Geben Sie die ngrok-IP-Adresse (vergessen Sie nicht, /api/messages hinzuzufügen) für die Bot-URL ein (z. B https://e58549b6.ngrok.io/api/messages. ).

    1. Geben Sie unter Microsoft App-ID die App-ID Ihres Bots ein.
    2. Geben Sie unter Microsoft App-Kennwort das App-Geheimnis Ihres Bots ein.
    3. Stellen Sie sicher, dass auch die Option Open in debug mode (Im Debugmodus öffnen) aktiviert ist.
    4. Wählen Sie Verbinden.
  3. Wenn der Debugmodus aktiviert ist, generiert der Emulator eine UUID. Eine UUID ist eine eindeutige ID, die jedes Mal generiert wird, wenn Sie den Debugmodus in Ihrem Emulator starten.

  4. Kopieren Sie die UUID, und fügen Sie sie in das Chatfeld Test in Webchat Chatbox Ihres Kanals ein. Im Chatfeld wird die Meldung "An die Sitzung angefügt, der gesamte Datenverkehr wird zur Überprüfung 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 zum Debuggen. Um den Nachrichtenstatus Ihres Bots zu überprüfen, wählen Sie Botstatus aus, und entfalten Sie die Werte im rechten JSON-Fenster.

debug-inspection-middleware

Zusätzliche Ressourcen