Debuggen eines Bots mit Middleware zur ÜberprüfungDebug a bot with inspection middleware

gilt für: SDK v4APPLIES TO: SDK v4

In diesem Artikel wird beschrieben, wie Sie einen Bot mit Middleware zur Überprüfung debuggen.This article describes how to debug a bot using inspection middleware. Diese Funktion ermöglicht es Bot Framework Emulator, den Datenverkehr in und aus dem Bot zu debuggen und den aktuellen Zustand des Bots zu überprüfen.This feature allows the Bot Framework Emulator to debug traffic into and out of the bot in addition to looking at the current state of the bot. Sie können eine Ablaufverfolgungsmeldung verwenden, um Daten an den Emulator zu senden und dann den Zustand Ihres Bots in einem beliebigen Durcheinander der Konversation zu überprüfen.You can use a trace message to send data to the Emulator and then inspect the state of your bot in any given turn of the conversation.

Wir verwenden einen EchoBot, der lokal mithilfe der Bot Framework v4(C#-JavaScript | | Java | Python)erstellt wurde, um zu zeigen, wie der Nachrichtenzustand des Bots debuggen und überprüft wird.We use an EchoBot built locally using the Bot Framework v4 (C# | JavaScript | Java | Python) to show how to debug and inspect the bot's message state. 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.You can also Debug a bot using IDE or Debug with the Bot Framework Emulator, but to debug state you need to add inspection middleware to your bot. Die Beispiele für den Untersuchungsbot sind hier verfügbar: C#, JavaScript, Java und Python.The Inspection bot samples are available here: C#, JavaScript, Java and Python.

VoraussetzungenPrerequisites

Aktualisieren Ihres Emulators auf die neueste VersionUpdate your Emulator to the latest version

Bevor Sie die Middleware für die Botuntersuchung zum Debuggen Ihres Bots verwenden, müssen Sie Ihren Emulator auf Version 4.5 oder höher aktualisieren.Before using the bot inspection middleware to debug your bot, you need to update your Emulator to be version 4.5 or newer. Informieren Sie sich über die aktuellen Updateversionen.Check the latest version for updates.

Klicken Sie im Menü auf Hilfe zu , um die Version Ihres Emulators zu > überprüfen.To check the version of your Emulator, select Help > About in the menu. Die aktuelle Version Ihres Emulators wird angezeigt.You will see the current version of your Emulator.

Aktuelle Version

Aktualisieren Ihres BotcodesUpdate your bot's code

Richten Sie die Untersuchung des Zustands ein, und fügen Sie die Middleware zur Überprüfung dem Adapter in der Datei Startup.cs hinzu.Set up the inspection state and add the inspection middleware to the adapter in the Startup.cs file. Die Untersuchung des Zustands wird per Abhängigkeitsinjektion bereitgestellt.The inspection state is provided through dependency injection. Sehen Sie sich unten das Codeupdate oder dieses Beispiel für die Untersuchung an: C#.See the code update below or refer to the inspection sample here: C#.

Startup.csStartup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient().AddControllers().AddNewtonsoftJson();

    services.AddSingleton<IStorage, MemoryStorage>();

    // The Inspection Middleware needs some scratch state to keep track of the (logical) listening connections.
    services.AddSingleton<InspectionState>();

    // You can inspect the UserState
    services.AddSingleton<UserState>();

    // You can inspect the ConversationState
    services.AddSingleton<ConversationState>();

    // Create the Bot Framework Adapter.
    services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithInspection>();

    // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
    services.AddTransient<IBot, EchoBot>();
}

AdapterWithInspection.csAdapterWithInspection.cs

public class AdapterWithInspection : CloudAdapter
{
    public AdapterWithInspection(IConfiguration configuration, IHttpClientFactory httpClientFactory, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
        : base(configuration, httpClientFactory, logger)
    {
        // Inspection needs credentiaols 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.Update the bot class in the EchoBot.cs file.

EchoBot.csEchoBot.cs

private readonly ConversationState _conversationState;
private readonly UserState _userState;

public EchoBot(ConversationState conversationState, UserState userState)
{
    _conversationState = conversationState;
    _userState = userState;
}

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    await base.OnTurnAsync(turnContext, cancellationToken);

    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
    await _userState.SaveChangesAsync(turnContext, false, cancellationToken);
}

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 BotsTest your bot locally

Nach dem Aktualisieren des Codes können Sie Ihren Bot lokal ausführen und das Debugfeature mithilfe von zwei Emulatoren testen: einen zum Senden und Empfangen von Nachrichten und den anderen zum Überprüfen des Status von Nachrichten im Debugmodus.After updating the code you can run your bot locally and test the debugging feature using two Emulators: one to send and receive messages, and the other to inspect the state of messages in debugging mode. Führen Sie die folgenden Schritte aus, um Ihren Bot lokal zu testen:To test your bot locally take the following steps:

  1. Navigieren Sie in einem Terminal zum Verzeichnis Ihres Bots, und verwenden Sie den folgenden Befehl, um Ihren Bot lokal auszuführen:Navigate to your bot's directory in a terminal and execute the following command to run your bot locally:

    dotnet run
    
  2. Öffnen Sie Ihren Emulator.Open your Emulator. Klicken Sie auf Bot öffnen.Click Open Bot. Geben Sie http://localhost:3978/api/messages als Bot-URL und die Werte für MicrosoftAppId und MicrosoftAppPassword an.Fill in Bot URL with http://localhost:3978/api/messages and the MicrosoftAppId and MicrosoftAppPassword values. Wenn Sie über einen JavaScript-Bot verfügen, finden Sie diese Werte in der ENV-Datei Ihres Bots.If you have a JavaScript bot you can find these values in your bot's .env file. Falls Sie einen C#-Bot nutzen, finden Sie diese Werte in der Datei appsettings.json.If you have a C# bot you can find these values in the appsettings.json file. Für einen Java-Bot finden Sie diese Werte in der Datei application.properties.For a Java bot you can find these values in the application.properties file. Klicken Sie auf Verbinden.Click Connect.

  3. Öffnen Sie nun ein weiteres Emulatorfenster.Now open another Emulator window. Dieses zweite Emulatorfenster funktioniert als Debugger.This second Emulator window will work as a debugger. Befolgen Sie die Anleitung aus dem vorherigen Schritt.Follow the instructions as described in the previous step. Aktivieren Sie die Option Open in debug mode (Im Debugmodus öffnen), und klicken Sie auf Verbinden.Check Open in debug mode and then click Connect.

  4. An diesem Punkt sehen Sie einen Befehl mit einem eindeutigen Bezeichner ( /INSPECT attach <identifier> ) in Ihrem Debugemulator.At this point you will see a command with a unique identifier (/INSPECT attach <identifier>) in your debugging Emulator. Kopieren Sie den gesamten Befehl mit dem Bezeichner aus dem Debugemulator, und fügen Sie ihn in das Chatfeld des ersten Emulators ein.Copy the whole command with the identifier from the debugging Emulator and paste it into the chat box of the first Emulator.

    Hinweis

    Ein eindeutiger Bezeichner wird jedes Mal generiert, wenn der Emulator im Debugmodus gestartet wird, nachdem Sie die Middleware für die Überprüfung im Code Ihres Bots hinzugefügt haben.A unique identifier is generated every time when the Emulator is launched in debug mode after you add the inspection middleware in your bot's code.

  5. Jetzt können Sie Nachrichten im Chatfeld Ihres ersten Emulators senden und die Nachrichten im Debugemulator überprüfen.Now you can send messages in the chat box of your first Emulator and inspect the messages in the debugging Emulator. Um den Status der Nachrichten zu überprüfen, klicken Sie im Debugemulator auf Bot State und wertet sie im rechten JSON-Fenster auf.To inspect the state of the messages click Bot State in the debugging Emulator and unfold values on the right JSON window. Der Status Ihres Bots wird im Debugemulator angezeigt:You will see the state of your bot in the debugging Emulator:

    Botzustand

Untersuchen des Zustands eines in Azure konfigurierten BotsInspect the state of a bot configured in Azure

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.If you want to inspect the state of your bot configured in Azure and connected to channels (like Teams) you will need to install and run ngrok.

Ausführen von ngrokRun ngrok

An diesem Punkt haben Sie Ihren Emulator auf die neueste Version aktualisiert und die Middleware für die Überprüfung im Code Ihres Bots hinzugefügt.At this point you have updated your Emulator to the latest version and added the inspection middleware in your bot's code. Der nächste Schritt besteht darin, ngrok auszuführen und Ihren lokalen Bot für die Azure-Botkanalregistrierung zu konfigurieren.The next step is to run ngrok and configure your local bot to your Azure Bot Channels Registration. Vor der ngrok-Ausführung müssen Sie Ihren Bot lokal ausführen.Before running ngrok you need to run your bot locally.

Gehen Sie wie folgt vor, um Ihren Bot lokal auszuführen:To run your bot locally do the following:

  1. Navigieren Sie in einem Terminal zum Ordner Ihres Bots, und legen Sie für Ihre npm-Registrierung fest, dass die aktuellen Builds verwendet werden sollen.Navigate to your bot's folder in a terminal and set your npm registration to use the latest builds

  2. Führen Sie Ihren Bot lokal aus.Run your bot locally. Sie sehen, dass Ihr Bot eine Portnummer wie verfügbar 3978 macht.You will see your bot expose a port number like 3978.

  3. Öffnen Sie eine weitere Eingabeaufforderung, und navigieren Sie zum Projektordner Ihres Bots.Open another command prompt and navigate to your bot's project folder. Führen Sie den folgenden Befehl aus:Run the following command:

    ngrok http 3978
    
  4. ngrok ist jetzt mit Ihrem lokal ausgeführten Bot verbunden.ngrok is now connected to your locally running bot. Kopieren Sie die öffentliche IP-Adresse.Copy the public IP address.

    ngrok-success

Aktualisieren von Kanalregistrierungen für Ihren BotUpdate channel registrations for your bot

Da Ihr lokaler Bot jetzt mit ngrok verbunden ist, können Sie ihn für die Botkanalregistrierung in Azure konfigurieren.Now that your local bot is connected to ngrok you can configure your local bot to your Bot Channels Registration in Azure.

  1. Navigieren Sie zu Ihrer Botkanalregistrierung in Azure.Go to your Bot Channels Registration in Azure. Klicken Sie im Menü auf der linken Seite auf Einstellungen, und legen Sie den Messaging-Endpunkt mit Ihrer ngrok-IP fest.Click Settings on the left menu and set the Messaging endpoint with your ngrok IP. Fügen Sie bei Bedarf nach der IP-Adresse /api/messages hinzu.If necessary add /api/messages after the IP address. Beispiel: https://e58549b6.ngrok.io/api/messages.For example, https://e58549b6.ngrok.io/api/messages. Aktivieren Sie Enable Streaming Endpoint (Streamingendpunkt aktivieren), und wählen Sie Speichern.Check Enable Streaming Endpoint and Save.

    endpoint

    Tipp

    Wenn Speichern nicht aktiviert ist, können Sie die Option Enable Streaming Endpoint (Streamingendpunkt aktivieren) deaktivieren und auf Speichern klicken. Aktivieren Sie anschließend die Option Enable Streaming Endpoint (Streamingendpunkt aktivieren) wieder, und klicken Sie erneut auf Speichern.If Save is not enabled, you can uncheck Enable Streaming Endpoint and click Save, then check Enable Streaming Endpoint and click Save again. Sie müssen sicherstellen, dass die Option Enable Streaming Endpoint (Streamingendpunkt aktivieren) aktiviert ist und die Konfiguration des Endpunkts gespeichert wird.You need to make sure that Enable Streaming Endpoint is checked and the configuration of the endpoint is saved.

  2. Navigieren Sie zur Ressourcengruppe Ihres Bots, klicken Sie auf Bereitstellung, und wählen Sie Ihre Botkanalregistrierung aus, die zuvor erfolgreich bereitgestellt wurde.Go to your bot's resource group, click Deployment, and select your Bot Channels Registration that previously deployed successfully. Klicken Sie auf der linken Seite auf Eingaben, um die Werte für appId und appSecret zu erhalten.Click Inputs on the left side to get the appId and appSecret. Aktualisieren Sie die ENV-Datei (oder bei Verwendung eines C#-Bots die Datei appsettings.json) mit den Werten für appId und appSecret.Update your bot's .env file (or appsettings.json file if you have a C# bot) with the appId and appSecret.

    get-inputs

  3. Starten Sie Ihren Emulator, klicken Sie auf Bot öffnen, und http://localhost:3978/api/messages geben Sie die Bot-URL ein.Start your Emulator, click Open Bot, and put http://localhost:3978/api/messages in the Bot URL. Fügen Sie für die Microsoft-App-ID und das Microsoft-App-Kennwort die gleichen Werte für appId und appSecret ein, die Sie der ENV-Datei (appsettings.json) des Bots hinzugefügt haben.Fill Microsoft App ID and Microsoft App password with the same appId and appSecret you added to our bot's .env (appsettings.json) file. Klicken Sie auf Verbinden.Then click Connect.

  4. Ihr ausgeführter Bot ist jetzt mit Ihrer Botkanalregistrierung in Azure verbunden.Your running bot is now connected to your Bot Channels Registration in Azure. Sie können den Webchat testen, indem Sie auf Test in Web Chat (In Webchat testen) klicken und im Chatfeld Nachrichten senden.You can test the web chat by clicking Test in Web Chat and sending messages in the chat box.

    test-web-chat

  5. Nun aktivieren wir den Debugmodus im Emulator.Now let's enable the debugging mode in the Emulator. Wählen Sie in Ihrem Emulator Debuggen > Debuggen starten aus.In your Emulator select Debug > Start Debugging. 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 ).Enter the ngrok IP address (don't forget to add /api/messages) for the Bot URL (for example, https://e58549b6.ngrok.io/api/messages). Geben Sie unter Microsoft App ID (Microsoft-App-ID) die App-ID Ihres Bots ein.For Microsoft App ID, enter your bot's app ID. Geben Sie unter Microsoft App Password (Microsoft-App-Kennwort) das App-Geheimnis Ihres Bots ein.For Microsoft App password, enter your bot's app secret. Stellen Sie sicher, dass auch die Option Open in debug mode (Im Debugmodus öffnen) aktiviert ist.Make sure Open in debug mode is checked as well. Klicken Sie auf Verbinden.Click Connect.

  6. Wenn der Debugmodus aktiviert ist, wird eine UUID in Ihrem Emulator generiert.When the debugging mode is enabled a UUID will be generated in your Emulator. Eine UUID ist eine eindeutige ID, die jedes Mal generiert wird, wenn Sie den Debugmodus in Ihrem Emulator starten.A UUID is a unique ID generated every time you start the debugging mode in your Emulator. Kopieren Sie den UUID, und fügen Sie ihn in das Chatfeld von Test in Web Chat (In Webchat testen) oder das Chatfeld Ihres Kanals ein.Copy and paste the UUID to the Test in Web Chat chat box or your channel's chat box. Im Chatfeld wird die Meldung „Attached to session, all traffic is being replicated for inspection“ (An Sitzung angefügt, der gesamte Datenverkehr wird für die Untersuchung repliziert) angezeigt.You will see the message "Attached to session, all traffic is being replicated for inspection" in the chat box.

Sie können mit dem Debuggen des Bots beginnen, indem Sie im Chatfeld des konfigurierten Kanals Nachrichten senden.You can start debugging your bot by sending messages in the configured channel's chat box. Ihr lokaler Emulator aktualisiert die Nachrichten automatisch mit allen Details zum Debuggen.Your local Emulator will automatically update the messages with all the details for debugging. Klicken Sie zum Untersuchen des Nachrichtenzustands Ihres Bots auf Botzustand, und erweitern Sie im JSON-Fenster auf der rechten Seite die Option Werte.To inspect your bot's state of messages click Bot State and unfold the values in the right JSON window.

debug-inspection-middleware

Zusätzliche RessourcenAdditional resources