Tester et déboguer avec Emulator

S’APPLIQUE À : SDK v4

Bot Framework Emulator est une application bureautique qui permet aux développeurs de bots de tester et déboguer leurs bots localement ou à distance. Emulator vous permet de converser avec le bot et d’inspecter les messages qu’il envoie et reçoit. Emulator affiche les messages tels qu’ils apparaîtraient dans une interface utilisateur de conversation Web, et journalise les requêtes et réponses JSON à mesure que vous échangez des messages avec le bot. Avant de déployer votre bot dans le Cloud, exécutez-le et testez-le localement à l’aide d’Emulator. Vous pouvez tester votre bot à l’aide d’Emulator, même si vous ne l’avez pas encore créé avec Azure AI Bot Service ou configuré pour s’exécuter sur des canaux.

Remarque

Les kits de développement logiciel (SDK) JavaScript, C# et Python bot Framework continueront d'être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est progressivement mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023. Seuls les correctifs de sécurité et de bogues critiques au sein de ce référentiel seront appliqués.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d'utiliser Power Virtual Agents et découvrez comment choisir la solution de chatbot appropriée.

Pour plus d'informations, consultez Les futures versions de bot.

Prérequis

Exécuter un robot localement

Avant de connecter votre robot au Bot Framework Emulator, vous devez exécuter votre robot localement. Vous pouvez utiliser Visual Studio ou Visual Studio Code pour exécuter votre robot ou utiliser la ligne de commande. Pour exécuter un robot à l’aide de la ligne de commande, procédez comme suit :

  • Allez à l’invite de commande et remplacez le répertoire par le répertoire de votre projet de robot.

  • Démarrez le robot en exécutant la commande suivante :

    dotnet run
    
  • Copiez le numéro de port dans la ligne avant Application démarrée. Appuyez sur Ctrl+C pour arrêter.

    C# port number

À ce stade, votre robot s’exécute localement.

Se connecter à un bot s’exécutant sur un hôte local

Configuration des paramètres de proxy

Lorsque vous développez derrière un proxy d’entreprise, Emulator utilise les variables d’environnement HTTP_PROXY et HTTPS_PROXY configurées, qui spécifient respectivement l’itinéraire d’URL du proxy pour les requêtes HTTP et HTTPs.

Si vous vous connectez à un bot qui s’exécute sur localhost, Emulator tente d’abord d’acheminer via le proxy avant de vous connecter à localhost. En règle générale, le proxy bloque la connexion, sauf si vous spécifiez qu’elle doit être contournée pour localhost.

Pour contourner les paramètres HTTP_PROXY et HTTPS_PROXY et autoriser Emulator à se connecter à localhost, vous devez définir la variable d’environnement suivante sur votre ordinateur local :

NO_PROXY=localhost

Configurer Emulator pour l’authentification

Si un bot nécessite une authentification par le biais d’une boîte de dialogue de connexion, vous devez configurer Emulator comme indiqué ci-dessous.

Utilisation d’un code de vérification de connexion

  1. Démarrez Emulator.
  2. Dans Emulator, sélectionnez Paramètres (icône d’engrenage) dans le volet gauche.
  3. Activez Contourner ngrok pour les adresses locales.
  4. Activez Utiliser un code de vérification de connexion pour OAuthCards.
  5. Sélectionnez Enregistrer.

Lorsque vous sélectionnez le bouton de connexion affiché par le bot, un code de validation est généré. Vous saisirez le code dans la zone de conversation d’entrée du bot pour établir l’authentification. Vous pouvez ensuite effectuer les opérations autorisées.

Sinon, vous pouvez effectuer les étapes décrites ci-dessous.

Utilisation de jetons d’authentification

  1. Démarrez Emulator.
  2. Dans Emulator, sélectionnez Paramètres (icône d’engrenage) dans le volet gauche.
  3. Saisissez le chemin local vers ngrok. Pour plus d’informations sur ngork consultez ngork.
  4. Activez Exécuter ngrok au démarrage d’Emulator.
  5. Activez Utiliser les jetons d’authentification version 1.0.
  6. Sélectionnez Enregistrer.

Lorsque vous sélectionnez le bouton de connexion affiché par le bot, vous êtes invité à entrer vos informations d’identification. Un jeton d’authentification est généré. Vous pouvez ensuite effectuer les opérations autorisées.

Emulator startup window

Pour vous connecter à un bot s’exécutant localement, sélectionnez Ouvrir le bot. Ajoutez le numéro de port que vous avez copié précédemment dans l’URL suivante et collez l’URL mise à jour dans la barre d’URL du robot :

http://localhost:<port number>/api/messages

Emulator open-a-bot dialog

Si votre bot s’exécute avec les informations d’identification de compte Microsoft (MSA), entrez également ces informations d’identification.

Utiliser les informations d’identification du bot

Lorsque vous ouvrez le bot, définissez l’ID d’application Microsoft et le mot de passe d’application Microsoft si votre bot s’exécute avec des informations d’identification. Si vous avez créé votre bot avec Azure AI Bot Service, les informations d’identification sont disponibles sur l’App Service du bot, sous la section Paramètres -> Configuration. Si vous ne connaissez pas les valeurs, vous pouvez les supprimer du fichier de configuration du bot exécuté localement, puis exécuter le bot dans Emulator. Si le bot n’est pas en cours d’exécution avec ces paramètres, vous n’avez pas besoin d’exécuter Emulator avec les paramètres.

Lors de la création d’une application de fournisseur d’identité Azure AD, gardez à l’esprit les points suivants :

  • Quand le type de comptes pris en charge est défini sur un locataire unique, si vous utilisez un abonnement personnel au lieu d’un compte Microsoft, Emulator émet le message d’erreur : L’ID ou le mot de passe du bot de l’application Microsoft est incorrect.
  • Dans ce cas, les types de comptes pris en charge doivent être définis sur Comptes dans un répertoire d’entreprise (tout répertoire Microsoft Entra ID - Multilocataire) et comptes Microsoft personnels (par exemple, Xbox).

Pour plus d’informations, consultez Créer une application de fournisseur d’identité Microsoft Entra ID et Inscrire une nouvelle application à l’aide du portail Azure.

Afficher les activités de message détaillées avec l’inspecteur

Envoyez un message à votre robot et ce dernier doit répondre. Vous pouvez sélectionnez la bulle du message dans la fenêtre de conversation et inspecter l’activité JSON brute à l’aide de la fonctionnalité INSPECTOR à droite de la fenêtre. Lorsque cette option est sélectionnée, la bulle de message devient jaune et l’objet JSON d’activité s’affiche à gauche de la fenêtre de conversation. Les informations JSON incluent des métadonnées clés, dont l’ID de canal, le type d’activité, l’ID de conversation, le SMS, l’URL du point de terminaison, etc. Vous pouvez inspecter les activités envoyées par l’utilisateur, ainsi que les activités avec lesquelles le bot répond.

Emulator message activity JSON

Conseil

Vous pouvez déboguer des modifications d’État dans un robot connecté à un canal en ajoutant un Intergiciel d’inspection au robot.

Inspecter des services

Remarque

Azure AI QnA Maker sera mis hors service le 31 mars 2025. À partir du 1er octobre 2022, vous ne pourrez plus créer de nouvelles ressources ou bases de connaissances QnA Maker. Une version plus récente de la fonctionnalité de questions et réponses est désormais disponible dans le cadre d’Azure AI Language.

La réponse aux questions personnalisées, une fonctionnalité d'Azure AI Language, est la version mise à jour du service QnA Maker. Pour plus d'informations sur la prise en charge des questions et réponses dans le kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Remarque

Compréhension du langage (LUIS) sera mis hors service le 1er octobre 2025. À compter du 1er avril 2023, vous ne pourrez pas créer de nouvelles ressources LUIS. Une version plus récente de Compréhension du langage est désormais disponible dans le cadre d'Azure AI Language.

Compréhension du langage conversationnel (CLU), une fonctionnalité d'Azure AI Language, est la version mise à jour de LUIS. Pour plus d'informations sur la prise en charge de compréhension du langage dans le kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Avec Emulator, vous pouvez également inspecter les réponses JSON à partir de LUIS et QnA Maker. À l’aide d’un robot avec un service de langage connecté, vous pouvez sélectionner trace dans la fenêtre LOG (JOURNAL) en bas à droite. Ce nouvel outil offre également des fonctionnalités pour mettre à jour vos services de langage directement à partir d’Emulator.

LUIS Inspector

Avec un service LUIS connecté, le lien de trace spécifie Trace LUIS. En suivant ce lien, la réponse brute de votre service LUIS s’affiche. Elle inclut des intentions, des entités avec leurs scores spécifiés. Vous pouvez réattribuer des intentions pour vos énoncés utilisateur.

QnA Inspector

Avec un service QnA Maker connecté, le journal d’activité affiche la trace QnA. Lorsqu’il est sélectionné, vous pouvez voir un aperçu de la paire question-réponse associée à cette activité, ainsi qu’un score de confiance. À partir de là, vous pouvez ajouter une autre formulation de question pour une réponse.

Connexion à Azure

Vous pouvez utiliser Emulator pour vous connecter à votre compte Azure. Cela vous est utile pour ajouter et gérer les services dont votre bot dépend. Pour vous connecter :

  1. Sélectionnez Fichier, puis Se connecter avec Azure.

    Emulator sign in with Azure

  2. Dans l’écran de Bienvenue, sélectionnez Se connecter avec votre compte Azure. Vous pouvez éventuellement indiquer à Emulator de maintenir votre connexion lors du redémarrage du programme d’émulation.

    Emulator Azure sign-in success

Désactivation de la collecte des données

Si vous ne voulez plus autoriser Emulator à collecter des données d’utilisation, vous pouvez facilement désactiver la collecte de données en effectuant les étapes suivantes :

  1. Dans Emulator, sélectionnez Paramètres (icône d’engrenage) dans le volet gauche.

    Emulator settings button

  2. Décochez la case Aidez-nous à améliorer Emulator en nous autorisant à collecter des données d’utilisation sous la section Collecte des données.

  3. Sélectionnez Enregistrer.

Si vous changez d’avis, vous pouvez réactiver la collecte de données ultérieurement.

Ressources supplémentaires

Bot Framework Emulator est open source. Vous pouvez contribuer au développement en envoyant des bogues et des suggestions.

Pour des informations de dépannage, consultez Résoudre les problèmes généraux ainsi que les autres articles de résolution des problèmes de cette section.

Étape suivante

Utilisez l’intergiciel d’inspection pour déboguer un robot connecté à un canal.