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
- 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.
- Installation von ngrok (falls Sie einen in Azure konfigurierten Bot debuggen möchten, um weitere Kanäle zu nutzen)
- Eine Kopie des Inspektions-Bot-Beispiels in C#, JavaScript, Java oder Python
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:
Navigieren Sie in einem Terminal zum Verzeichnis Ihres Bots, und verwenden Sie den folgenden Befehl, um Ihren Bot lokal auszuführen:
dotnet run
Ö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.Ö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.
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.
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 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:
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
Führen Sie Ihren Bot lokal aus. Sie sehen, dass von Ihrem Bot eine Portnummer wie
3978
verfügbar gemacht wird.Öffnen Sie eine weitere Eingabeaufforderung, und gehen Sie zum Projektordner Ihres Bots. Führen Sie den folgenden Befehl aus:
ngrok http 3978
ngrok ist jetzt mit Ihrem lokal ausgeführten Bot verbunden. Kopieren Sie die sichere (HTTPS) öffentliche IP-Adresse.
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.
Wechseln Sie zu Ihrer Bot-Ressource in Azure. Wählen Sie im linken Menü unterEinstellungen die Option Konfiguration.
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
.Wählen Sie Streamingendpunkt aktivieren.
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.
Wechseln Sie zu Ihrer Bot-Ressourcengruppe.
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.
Aktualisieren Sie die Konfigurationsdatei Ihres Bots (appsettings.json für C# oder .env für JavaScript) mit der MicrosoftAppId und dem MicrosoftAppPassword.
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.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:
Wählen Sie im Emulator die Option Debuggen, dann Debugging starten.
Fügen Sie die ngrok-IP-Adresse (Zusatz /api/messages nicht vergessen) unter Bot-URL ein (z. B.
https://e58549b6.ngrok.io/api/messages
).- Geben Sie als Microsoft App-ID die App-ID Ihres Bots ein.
- Geben Sie als Microsoft App-Kennwort den geheimen App-Schlüssel Ihres Bots ein.
- Stellen Sie sicher, dass auch die Option Im Debugmodus öffnen aktiviert ist.
- Wählen Sie Verbinden aus.
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.
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