Déboguer un robot avec un intergiciel d’inspectionDebug a bot with inspection middleware

s’applique à : SDK v4APPLIES TO: SDK v4

Cet article explique comment déboguer un bot à l’aide d’un intergiciel (middleware) d’inspection.This article describes how to debug a bot using inspection middleware. Cette fonctionnalité permet à l’émulateur Bot Framework Emulator de déboguer le trafic transitant par le bot, en plus d’inspecter l’état actuel du bot.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. vous pouvez utiliser un message de suivi pour envoyer des données au Emulator puis inspecter l’état de votre bot dans n’importe quel tour de la conversation.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.

Nous utilisons un EchoBot généré localement à l’aide de bot Framework v4 créer un bot pour montrer comment déboguer et inspecter l’état du message du bot.We use an EchoBot built locally using the Bot Framework v4 Create a bot to show how to debug and inspect the bot's message state. Vous pouvez aussi Déboguer un bot à l’aide de l’IDE ou le Déboguer avec Bot Framework Emulator, mais pour déboguer l’état, vous devez ajouter l’intergiciel d’inspection à votre bot.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. Les exemples de bot d’inspection sont disponibles ici : C#, JavaScript, java et python.The Inspection bot samples are available here: C#, JavaScript, Java and Python.

PrérequisPrerequisites

mettre à jour votre Emulator avec la dernière versionUpdate your Emulator to the latest version

avant d’utiliser l’intergiciel (middleware) d’inspection de bot pour déboguer votre robot, vous devez mettre à jour votre Emulator en version 4,5 ou une version plus récente.Before using the bot inspection middleware to debug your bot, you need to update your Emulator to be version 4.5 or newer. Vérifiez la dernière version des mises à jour.Check the latest version for updates.

pour vérifier la version de votre Emulator, sélectionnez aide > à propos de dans le menu.To check the version of your Emulator, select Help > About in the menu. La version actuelle de votre Emulator s’affiche.You will see the current version of your Emulator.

version actuelle

Mettre à jour le code de votre robotUpdate your bot's code

Configurez l’état d’inspection et ajoutez le middleware d’inspection à l’adaptateur dans le fichier Startup.cs.Set up the inspection state and add the inspection middleware to the adapter in the Startup.cs file. L’état d’inspection est fourni par injection de dépendances.The inspection state is provided through dependency injection. Consultez la mise à jour du code ci-dessous ou reportez-vous à l’exemple d’inspection ici : 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");
        };
    }
}

Mettez à jour la classe de bot dans le fichier 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++;
}

Tester votre bot localementTest your bot locally

Après la mise à jour du code, vous pouvez exécuter votre bot localement et tester la fonctionnalité de débogage à l’aide de deux émulateurs : l’un pour envoyer et recevoir des messages, et l’autre pour inspecter l’état des messages en mode débogage.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. Pour tester votre robot localement, procédez comme suit :To test your bot locally take the following steps:

  1. Accédez au répertoire de votre bot dans un terminal et exécutez la commande suivante pour exécuter votre robot localement :Navigate to your bot's directory in a terminal and execute the following command to run your bot locally:

    dotnet run
    
  2. Ouvrez votre Emulator.Open your Emulator. Cliquez sur Ouvrir le robot.Click Open Bot. Renseignez l’URL du robot avec http://localhost:3978/api/messages et les valeurs MicrosoftAppId et MicrosoftAppPassword.Fill in Bot URL with http://localhost:3978/api/messages and the MicrosoftAppId and MicrosoftAppPassword values. Si vous avez un robot JavaScript, vous pouvez trouver ces valeurs dans le fichier .env de votre robot.If you have a JavaScript bot you can find these values in your bot's .env file. Si vous avez un robot C#, vous pouvez trouver ces valeurs dans le fichier appSettings.json.If you have a C# bot you can find these values in the appsettings.json file. Pour un robot Java, vous pouvez trouver ces valeurs dans le fichier application. Properties .For a Java bot you can find these values in the application.properties file. Cliquez sur Connecter.Click Connect.

  3. à présent, ouvrez une autre fenêtre de Emulator.Now open another Emulator window. cette deuxième Emulator fenêtre fonctionnera en tant que débogueur.This second Emulator window will work as a debugger. Suivez les instructions décrites à l’étape précédente.Follow the instructions as described in the previous step. Cochez Ouvrir en mode débogage et cliquez sur Se connecter.Check Open in debug mode and then click Connect.

  4. À ce stade, vous verrez une commande avec un identificateur unique ( /INSPECT attach <identifier> ) dans votre Emulator de débogage.At this point you will see a command with a unique identifier (/INSPECT attach <identifier>) in your debugging Emulator. Copiez la commande entière avec l’identificateur depuis l’émulateur de débogage et collez-la dans la zone de conversation du premier émulateur.Copy the whole command with the identifier from the debugging Emulator and paste it into the chat box of the first Emulator.

    Notes

    un identificateur unique est généré chaque fois que la Emulator est lancée en mode débogage après que vous avez ajouté l’intergiciel d’inspection dans le code de votre bot.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. vous pouvez désormais envoyer des messages dans la zone de conversation de votre première Emulator et inspecter les messages dans le Emulator de débogage.Now you can send messages in the chat box of your first Emulator and inspect the messages in the debugging Emulator. pour inspecter l’état des messages, cliquez sur Bot State dans les Emulator de débogage et les valeurs de dérouler dans la fenêtre JSON appropriée.To inspect the state of the messages click Bot State in the debugging Emulator and unfold values on the right JSON window. Vous verrez l’état de votre bot dans le Emulator de débogage :You will see the state of your bot in the debugging Emulator:

    état de bot

Inspecter l’état d’un bot configuré dans AzureInspect the state of a bot configured in Azure

Si vous souhaitez inspecter l’état de votre robot configuré dans Azure et connecté à des canaux (comme Teams), vous devez installer et exécuterngrok.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.

Exécuter ngrokRun ngrok

à ce stade, vous avez mis à jour votre Emulator vers la dernière version et ajouté l’intergiciel d’inspection dans le code de votre bot.At this point you have updated your Emulator to the latest version and added the inspection middleware in your bot's code. L’étape suivante consiste à exécuter ngrok et à configurer votre robot local sur l’inscription de vos canaux de robots Azure.The next step is to run ngrok and configure your local bot to your Azure Bot Channels Registration. Avant d’exécuter ngrok, vous devez exécuter votre robot localement.Before running ngrok you need to run your bot locally.

Pour développer votre robot localement, procédez comme suit :To run your bot locally do the following:

  1. Accédez au dossier de votre robot dans un terminal et définissez votre inscription npm pour utiliser les builds les plus récentsNavigate to your bot's folder in a terminal and set your npm registration to use the latest builds

  2. Exécutez votre bot en local.Run your bot locally. Vous verrez que votre robot expose un numéro de port comme 3978 .You will see your bot expose a port number like 3978.

  3. Ouvrez une autre invite de commandes et accédez au dossier du projet de votre robot.Open another command prompt and navigate to your bot's project folder. Exécutez la commande suivante :Run the following command:

    ngrok http 3978
    
  4. ngrok est maintenant connecté à votre robot s’exécutant localement.ngrok is now connected to your locally running bot. Copiez l’adresse IP publique.Copy the public IP address.

    ngrok-success

Mettre à jour les inscriptions de canaux pour votre robotUpdate channel registrations for your bot

Maintenant que votre robot local est connecté à ngrok, vous pouvez configurer votre robot local pour l’inscription de vos canaux de robots dans Azure.Now that your local bot is connected to ngrok you can configure your local bot to your Bot Channels Registration in Azure.

  1. Allez à l’inscription aux canaux pour votre robot dans Azure.Go to your Bot Channels Registration in Azure. Cliquez sur Paramètres dans le menu de gauche, puis, définissez le Point de terminaison de messagerie avec votre adresse IP ngrok.Click Settings on the left menu and set the Messaging endpoint with your ngrok IP. Si nécessaire, ajoutez /api/messages à la suite de votre adresse IP.If necessary add /api/messages after the IP address. Par exemple : https://e58549b6.ngrok.io/api/messages.For example, https://e58549b6.ngrok.io/api/messages. Cochez Activer le point de terminaison de streaming et Enregistrer.Check Enable Streaming Endpoint and Save.

    endpoint

    Conseil

    Si Enregistrer n’est pas coché, vous pouvez décocher Activer le point de terminaison de streaming et cliquer sur Enregistrer, puis cocher Activer le point de terminaison de streaming et cliquez sur Enregistrer à nouveau.If Save is not enabled, you can uncheck Enable Streaming Endpoint and click Save, then check Enable Streaming Endpoint and click Save again. Vous devez vérifier que l’option Activer le point de terminaison de streaming est cochée et que la configuration du point de terminaison est enregistrée.You need to make sure that Enable Streaming Endpoint is checked and the configuration of the endpoint is saved.

  2. Allez au groupe de ressources de votre robot, cliquez sur Déploiement, puis sélectionnez l’inscription de vos canaux de robots qui a été précédemment déployée avec succès.Go to your bot's resource group, click Deployment, and select your Bot Channels Registration that previously deployed successfully. Cliquez sur Entrées à gauche pour accéder à appId et appSecret.Click Inputs on the left side to get the appId and appSecret. Mettez à jour le fichier .env de votre robot (ou le fichier appSettings.json si vous avez un robot C#) avec appId et 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. démarrez votre Emulator, cliquez sur ouvrir le robot et placez http://localhost:3978/api/messages l' URL du bot.Start your Emulator, click Open Bot, and put http://localhost:3978/api/messages in the Bot URL. Renseignez l’ID de l’application Microsoft et le mot de passe de l’application Microsoft avec le appId et appSecret ajouté au fichier .env (appsettings.json) de votre robot.Fill Microsoft App ID and Microsoft App password with the same appId and appSecret you added to our bot's .env (appsettings.json) file. Puis, cliquez sur Se connecter.Then click Connect.

  4. Votre robot en cours d’exécution est maintenant connecté à l’inscription de vos canaux de robot dans Azure.Your running bot is now connected to your Bot Channels Registration in Azure. Vous pouvez tester la conversation Web en cliquant sur Tester dans la discussion Web et en envoyant des messages dans la zone de discussion.You can test the web chat by clicking Test in Web Chat and sending messages in the chat box.

    test-web-chat

  5. Nous allons maintenant activer le mode de débogage dans le Emulator.Now let's enable the debugging mode in the Emulator. dans votre Emulator sélectionnez déboguer > démarrer le débogage.In your Emulator select Debug > Start Debugging. Entrez l’adresse IP ngrok (n’oubliez pas d’ajouter /API/messages) pour l' URL du bot (par exemple, 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). Pour ID d’application Microsoft, entrez l’ID d’application de votre bot.For Microsoft App ID, enter your bot's app ID. Pour mot de passe de l’application Microsoft, entrez le secret de l’application de votre bot.For Microsoft App password, enter your bot's app secret. Assurez-vous que la case Ouvrir en mode débogage est également cochée.Make sure Open in debug mode is checked as well. Cliquez sur Connecter.Click Connect.

  6. Lorsque le mode de débogage est activé, un UUID est généré dans votre Emulator.When the debugging mode is enabled a UUID will be generated in your Emulator. Un UUID est un ID unique généré chaque fois que vous démarrez le mode de débogage dans votre Emulator.A UUID is a unique ID generated every time you start the debugging mode in your Emulator. Copiez et collez l’UUID dans la zone de discussion Tester dans une discussion Web ou dans la zone de discussion de votre canal.Copy and paste the UUID to the Test in Web Chat chat box or your channel's chat box. Le message « joint à la session, tout le trafic est répliqué pour inspection » s’affiche dans la zone de discussion.You will see the message "Attached to session, all traffic is being replicated for inspection" in the chat box.

Vous pouvez démarrer le débogage de votre robot en envoyant des messages dans la zone de discussion du canal configuré.You can start debugging your bot by sending messages in the configured channel's chat box. votre Emulator local met automatiquement à jour les messages avec tous les détails du débogage.Your local Emulator will automatically update the messages with all the details for debugging. Pour inspecter l’état des messages de votre robot, cliquez sur Bot State et dépliez les valeurs dans la fenêtre JSON appropriée.To inspect your bot's state of messages click Bot State and unfold the values in the right JSON window.

debug-inspection-middleware

Ressources supplémentairesAdditional resources