Testen und Debuggen mit dem Emulator
GILT FÜR: SDK v4
Der Bot Framework Emulator ist eine Desktopanwendung, mit der Botentwickler ihre Bots lokal oder remote testen und debuggen können. Über den Emulator können Sie mit Ihrem Bot chatten und die Nachrichten untersuchen, die Ihr Bot sendet und empfängt. Der Emulator zeigt Nachrichten so an wie in einer Webchat-Benutzeroberfläche und protokolliert JSON-Anforderungen und -Antworten, während Sie mit Ihrem Bot kommunizieren. Führen Sie Ihren Bot vor der Bereitstellung in der Cloud lokal aus, und testen Sie ihn mithilfe des Emulators. Sie können Ihren Bot auch mit dem Emulator testen, wenn Sie ihn noch nicht mit Azure KI Bot Service erstellt oder für die Ausführung in Kanälen konfiguriert haben.
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
- Installieren Sie den Bot Framework-Emulator.
Lokales Ausführen eines Bots
Bevor Sie Ihren Bot mit dem Bot Framework Emulator verbinden, müssen Sie ihn lokal ausführen. Sie können Visual Studio oder Visual Studio Code oder die Befehlszeile verwenden, um Ihren Bot auszuführen. Gehen Sie wie folgt vor, um einen Bot über die Befehlszeile auszuführen:
Wechseln Sie zur Eingabeaufforderung und dann zum Verzeichnis Ihres Botprojekts.
Starten Sie den Bot, indem Sie den folgenden Befehl ausführen:
dotnet runKopieren Sie die Portnummer in der Zeile, bevor die Anwendung gestartet wird. Drücken Sie STRG+C, um herunterzufahren.
Ihr Bot sollte jetzt lokal ausgeführt werden.
Verbinden mit auf Localhost ausgeführten Bots
Konfigurieren von Proxyeinstellungen
Wenn Sie hinter einem Unternehmensproxy entwickeln, verwendet der Emulator die konfigurierten Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY, welche die Proxy-URL-Route für HTTP- und HTTPs-Anforderungen angeben.
Wenn Sie eine Verbindung mit einem Bot herstellen, der auf localhost ausgeführt wird, versucht der Emulator zunächst, den Proxy weiterzuleiten, bevor Sie eine Verbindung zu localhost herstellen. In der Regel blockiert der Proxy die Verbindung, es sei denn, Sie geben an, dass sie für localhost umgangen werden soll.
Um die Einstellungen HTTP_PROXY und HTTPS_PROXY zu umgehen und dem Emulator die Verbindung zu localhost zu ermöglichen, müssen Sie auf Ihrem lokalen Computer die folgende Umgebungsvariable definieren:
NO_PROXY=localhost
Konfigurieren des Emulators für die Authentifizierung
Wenn für einen Bot Authentifizierung erforderlich ist und ein Anmeldedialog angezeigt wird, müssen Sie den Emulator wie nachfolgend gezeigt konfigurieren.
Verwenden eines Anmelde-Prüfcodes
- Starten Sie den Emulator.
- Wählen Sie im Emulator Einstellungen (Zahnradsymbol) im linken Bereich aus.
- Aktivieren Sie Bypass ngrok überbrücken für lokale Adressen.
- Aktivieren Sie Anmeldeprüfcode für OAuthCards verwenden.
- Wählen Sie Speichern.
Wenn Sie auf die vom Bot angezeigte Anmeldeschaltfläche klicken, wird ein Validierungscode generiert. Geben Sie den Code in das Chatfeld des Bots ein, damit die Authentifizierung ausgeführt werden kann. Danach können die zulässigen Vorgänge ausgeführt werden.
Alternativ können Sie die unten beschriebenen Schritte ausführen.
Verwenden von Authentifizierungstoken
- Starten Sie den Emulator.
- Wählen Sie im Emulator Einstellungen (Zahnradsymbol) im linken Bereich aus.
- Geben Sie den lokalen Pfad zu ngrok ein. Weitere Informationen zu ngrok finden Sie unter ngrok.
- Aktivieren Sie ngrok ausführen, wenn der Emulator gestartet wird.
- Aktivieren Sie Authentifizierungstoken der Version 1.0 verwenden.
- Wählen Sie Speichern.
Wenn Sie auf die vom Bot angezeigte Anmeldeschaltfläche klicken, werden Sie zur Eingabe Ihrer Anmeldedaten aufgefordert. Ein Authentifizierungstoken wird generiert. Danach können die zulässigen Vorgänge ausgeführt werden.
Um einen lokal ausgeführten Bots zu verbinden, wählen Sie Bot öffnen. Fügen Sie die zuvor kopierte Portnummer der folgenden URL hinzu, und fügen Sie die aktualisierte URL in der Bot-URL-Leiste ein:
http://localhost:<port number>/api/messages
Geben Sie auch die Anmeldeinformationen des Microsoft-Kontos ein, falls Ihr Bot damit ausgeführt wird.
Verwenden von Bot-Anmeldeinformationen
Wenn Sie den Bot öffnen, legen Sie die Microsoft-App-ID und das Microsoft-App-Kennwort fest, falls Ihr Bot mit Anmeldeinformationen ausgeführt wird. Wenn Sie Ihren Bot mit Azure KI Bot Service erstellt haben, sind die Anmeldeinformationen im App Service des Bot im Abschnitt Einstellungen -> Konfiguration verfügbar. Wenn Sie die Werte nicht kennen, können Sie sie aus der Konfigurationsdatei des lokal ausgeführten Bots entfernen und den Bot dann im Emulator ausführen. Wenn der Bot nicht mit diesen Einstellungen ausgeführt wird, müssen Sie auch den Emulator nicht mit den Einstellungen ausführen.
Beachten Sie beim Erstellen einer AD-Identitätsanbieteranwendung Folgendes:
- Wenn die unterstützten Kontotypen auf einen einzelnen Mandanten festgelegt sind, gibt der Emulator den folgenden Fehler aus, wenn Sie anstelle eines Microsoft-Kontos ein persönliches Abonnement verwenden: Die Microsoft App ID oder das Microsoft App-Passwort des Bots sind falsch.
- In diesem Fall muss für die unterstützten Kontotypen die Option Konten in allen Organisationsverzeichnissen (beliebiges Microsoft Entra ID-Verzeichnis - mehrere Mandanten) und persönliche Microsoft-Konten (z. B. Xbox) ausgewählt werden.
Weitere Informationen finden Sie unter Erstellen einer Microsoft Entra-Identitätsanbieteranwendung und Registrieren einer neuen Anwendung mithilfe des Azure-Portals.
Anzeigen detaillierter Nachrichtenaktivitäten im Inspektor
Senden Sie eine Nachricht an Ihren Bot. Der Bot sollte dann mit einer Antwort reagieren. Sie können im Konversationsfenster eine Nachrichtenblase auswählen und die unformatierte JSON-Aktivität mit der Funktion INSPECTOR rechts neben dem Fenster überprüfen. Bei Auswahl wird die Nachrichtenblase gelb und das JSON-Aktivitätsobjekt wird links neben dem Chatfenster angezeigt. Die JSON-Informationen enthalten wichtige Metadaten z. B. Kanal-ID, Aktivitätstyp, Konversations-ID, Textnachricht, Endpunkt-URL usw. Sie können die vom Benutzer gesendeten Aktivitäten sowie die Aktivitäten einsehen, mit denen der Bot antwortet.
Tipp
Sie können Zustandsänderungen für einen mit einem Kanal verbundenen Bot debuggen, indem Sie ihm Middleware zur Überprüfung hinzufügen.
Dienste überprüfen
Hinweis
Azure KI QnA Maker wird am 31. März 2025 eingestellt. Ab dem 01. Oktober 2022 können Sie keine neuen QnA Maker-Ressourcen oder Wissensdatenbanken mehr erstellen. Eine neuere Version der Funktionalität „Fragen und Antworten“ ist jetzt als Teil von Azure KI Language verfügbar.
Benutzerdefiniertes Fragen und Antworten, eine Azure KI Language-Funktion, ist die aktualisierte Version des QnA Maker-Diensts. Weitere Informationen zur Unterstützung von Fragen und Antworten im Bot Framework SDK finden Sie unter Natürliches Sprachverständnis.
Hinweis
Language Understanding (LUIS) wird am 1. Oktober 2025 eingestellt. Ab dem 1. April 2023 können Sie keine neuen LUIS-Ressourcen erstellen. Eine neuere Version von Language Understanding ist jetzt als Teil von Azure KI Language verfügbar.
Conversational Language Understanding (CLU), ein Feature von Azure KI Language, ist die aktualisierte Version von LUIS. Weitere Informationen zu Language Understanding im Bot Framework-SDK finden Sie unter Natürliches Sprachverständnis.
Mit dem Emulator können Sie auch die JSON-Antworten von LUIS und QnA Maker überprüfen. Wenn Sie einen Bot mit einem verbundenen Sprachdienst verwenden, können Sie im Protokollfenster (LOG) unten rechts trace auswählen. Dieses neue Tool bietet auch Funktionen zur Aktualisierung Ihrer Sprachdienste direkt über den Emulator.
Bei einem verbundenen LUIS-Dienst gibt der Ablaufverfolgungslink LUIS-Ablauf an. Wenn Sie diese Option auswählen, sehen Sie die unverarbeitete Antwort Ihres LUIS-Dienstes, die die Absichten und Entitäten mit den angegebenen Bewertungen enthält. Sie können Absichten für Benutzer-Äußerungen neu zuweisen.
Bei einem verbundenen QnA Maker-Dienst zeigt das Protokoll die QnA-Ablaufverfolgung an. Wenn Sie diese Option auswählen, können Sie eine Vorschau des Frage-Antwort-Paares dieser Aktivität zusammen mit einer Konfidenzbewertung ansehen. Dann können Sie alternative Fragen für eine Antwort formulieren.
Anmelden bei Azure
Sie können den Emulator verwenden, um sich bei Ihrem Azure-Konto anzumelden. Dies ist besonders hilfreich für Sie, wenn es um das Hinzufügen und Verwalten von Diensten geht, von denen Ihr Bot abhängig ist. So melden Sie sich an:
Wählen Sie Datei und melden Sie sich mit Azure an.
Wählen Sie auf der Willkommensseite die Option Mit Ihrem Azure-Konto anmelden. Sie können optional angeben, dass die Anmeldung für den Emulator bei Neustarts der Emulatoranwendung erhalten bleibt.
Deaktivieren der Datensammlung
Wenn Sie sich dafür entscheiden, dass Sie für den Emulator das Erfassen von Nutzungsdaten nicht mehr zulassen möchten, können Sie die Datensammlung mit den folgenden Schritten leicht deaktivieren:
Wählen Sie im Emulator Einstellungen (Zahnradsymbol) im linken Bereich aus.
Deaktivieren Sie im Abschnitt Datensammlung das Kontrollkästchen Zur Verbesserung des Emulators beitragen, indem die Erfassung von Nutzungsdaten zugelassen wird.
Wählen Sie Speichern.
Wenn Sie Ihre Meinung ändern, können Sie die Datensammlung später erneut aktivieren.
Zusätzliche Ressourcen
Der Bot Framework-Emulator ist eine Open Source-Ressource. Sie können zur Entwicklung beitragen sowie Fehler melden und Vorschläge einbringen.
Informationen zur Problembehandlung finden Sie unter Behandeln allgemeiner Probleme und in den anderen Artikeln zur Problembehandlung in diesem Abschnitt.
Nächster Schritt
Verwenden Sie die Middleware zur Überprüfung, um einen mit einem Kanal verbundenen Bot zu debuggen.