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.

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

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

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

Voraussetzungen

• Kenntnisse zu Bot-Middleware und Statusverwaltung
• Kenntnisse zum Debuggen eines SDK-first-Bots und Testen und Debuggen mit dem Emulator
• Installation von Bot Framework-Emulator.
• Ein Dev Tunnel installieren (wenn Sie einen bot debuggen möchten, der in Azure für die Verwendung anderer Kanäle konfiguriert ist)
• Eine Kopie des Inspektions-Bot-Beispiels in C#, JavaScript, Java oder Python

Update Ihres Emulators auf die aktuellste Version

Bevor Sie Bot-Inspektions-Middleware zum Debuggen Ihres Bots verwenden, aktualisieren Sie Ihren Emulator auf Version 4.15 oder höher. 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

C#

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++;
}

JavaScript

Vor dem Codeupdate für Ihren Bot sollten Sie die zugehörigen Pakete auf die aktuellen Versionen aktualisieren, indem Sie den folgenden Befehl in Ihrem Terminal ausführen:

npm install --save botbuilder@latest

Anschließend müssen Sie den Code Ihres JavaScript-Bots wie hier angegeben aktualisieren. Weitere Informationen finden Sie hier: Aktualisieren Sie den Code Ihres Bots oder im Inspektions-Middleware-Beispiel auf GitHub.

index.js

Richten Sie die Untersuchung des Zustands ein, und fügen Sie die Middleware zur Überprüfung dem Adapter in der Datei index.js hinzu.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

Aktualisieren Sie die Botklasse in der Datei bot.js.

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

Richten Sie den Inspektionsstatus ei, und fügen Sie die Inspektions-Middleware dem Adapter in der Datei Startup.cs hinzu. Der Inspektionsstatus wird festgelegt, indem ein neuer String @Bean bereitgestellt wird, um den BotFrameworkHttpAdapter bereitzustellen, der auf @Primary festgelegt ist, damit er den von der BotDependencyConfiguration-Basisklasse standardmäßig bereitgestellten BotFrameworkHttpAdapter überschreibt. Sehen Sie sich unten das Codeupdate oder dieses Beispiel für Inspektions-Middleware an:

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection wird als Teil des Com.microsoft.bot.integration-Pakets implementiert und kann aus dem Java SDK-Quellcode überprüft werden.

Aktualisieren Sie die Botklasse in der Datei EchoBot.java.

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Bevor Sie den Code Ihres Bots aktualisieren, müssen Sie die erforderlichen PyPI-Pakete installieren, indem Sie in einem Terminal die folgenden Befehle ausführen:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Richten Sie die Untersuchung des Zustands in der Datei app.py ein, indem Sie dem Adapter Middleware hinzufügen.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

Aktualisieren Sie die Botklasse in der Datei bot.js.

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

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:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

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.

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:

   

Untersuchen des Zustands eines in Azure konfigurierten Bots

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

Ausführen von Devtunnel

Sie haben Ihren Emulator jetzt auf die aktuelle Version aktualisiert und die Inspektions-Middleware im Code Ihres Bots hinzugefügt. Der nächste Schritt besteht darin, devtunnel auszuführen und Ihren lokalen Bot zu konfigurieren. Bevor Sie devtunnel ausführen, 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:

   devtunnel host -a -p 3978
   

4. devtunnel ist jetzt mit Ihrem lokal ausgeführten Bot verbunden. Kopieren Sie die öffentliche URL (Secure, HTTPS).

   

Aktualisieren Sie Ihre Bot-Ressource

Nachdem Ihr lokaler Bot mit devtunnel verbunden ist, können Sie Ihre Bot-Ressource in Azure so konfigurieren, dass sie die Devtunnel-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 von Ihnen kopierte Devtunnel-URL-Adresse fest. Fügen Sie bei Bedarf nach der IP-Adresse /api/messages hinzu. Beispiel: https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Wählen Sie Streamingendpunkt aktivieren.

      

   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.

      

   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. Geben Sie die Devtunnel-URL ein (vergessen Sie nicht, /api/messages) für die Bot-URL (z. Bhttps://4jj51x75-51865.usw2.devtunnels.ms/api/messages. ) hinzuzufügen.

   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.

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.

Nächste Schritte

• Lernen Sie, wie Sie Ihren Bot mit Transkriptdateien debuggen
• Lernen Sie, wie Sie einen Skill oder Skill-Heimanwender debuggen