Depuración de un bot con middleware de inspecciónDebug a bot with inspection middleware

se aplica a: SDK V4APPLIES TO: SDK v4

En este artículo se describe cómo depurar un bot mediante middleware de inspección.This article describes how to debug a bot using inspection middleware. Esta característica permite a Bot Framework Emulator depurar el tráfico dentro y fuera del bot, además de examinar el estado actual de este.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. Puede usar un mensaje de seguimiento para enviar datos al emulador y, a continuación, inspeccionar el estado del bot en cualquier turno determinado de la conversación.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.

Usamos un EchoBot creado localmente mediante Bot Framework v4(JavaScriptpara Java Python de C#) para mostrar cómo depurar e inspeccionar el estado del mensaje | | | del bot.We use an EchoBot built locally using the Bot Framework v4 (C# | JavaScript | Java | Python) to show how to debug and inspect the bot's message state. También puede depurar mediante IDE o con Bot Framework Emulator pero para depurar el estado necesitará agregar un middleware de inspección al 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. Los ejemplos de bot de inspección están disponibles aquí: C#, JavaScript, Java y Python.The Inspection bot samples are available here: C#, JavaScript, Java and Python.

Requisitos previosPrerequisites

Actualización del emulador a la versión más recienteUpdate your Emulator to the latest version

Antes de usar el middleware de inspección de bots para depurar el bot, debe actualizar el emulador para que sea la versión 4.5 o posterior.Before using the bot inspection middleware to debug your bot, you need to update your Emulator to be version 4.5 or newer. Compruebe la versión más reciente para buscar actualizaciones.Check the latest version for updates.

Para comprobar la versión del emulador, seleccione Ayuda > sobre en el menú.To check the version of your Emulator, select Help > About in the menu. Verá la versión actual del emulador.You will see the current version of your Emulator.

versión actual

Actualización del código del botUpdate your bot's code

Configure el estado de inspección y agregue el middleware de inspección al adaptador en el archivo Startup.cs.Set up the inspection state and add the inspection middleware to the adapter in the Startup.cs file. El estado de inspección se proporciona mediante la inserción de dependencias.The inspection state is provided through dependency injection. Vea la siguiente actualización del código o consulte este ejemplo de inspección aquí: 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");
        };
    }
}

Actualice la clase del bot en el archivo 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++;
}

Prueba local del botTest your bot locally

Después de actualizar el código, puede ejecutar el bot localmente y probar la característica de depuración mediante dos emuladores: uno para enviar y recibir mensajes, y el otro para inspeccionar el estado de los mensajes en modo de depuración.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. Para probar el bot localmente, realice los pasos siguientes:To test your bot locally take the following steps:

  1. Vaya al directorio del bot en un terminal y ejecute el siguiente comando para ejecutar el bot localmente:Navigate to your bot's directory in a terminal and execute the following command to run your bot locally:

    dotnet run
    
  2. Abra el emulador.Open your Emulator. Haga clic en Open Bot (Abrir bot).Click Open Bot. Rellene la dirección URL del bot con http://localhost:3978/api/messages y los valores MicrosoftAppId y MicrosoftAppPassword.Fill in Bot URL with http://localhost:3978/api/messages and the MicrosoftAppId and MicrosoftAppPassword values. Si tiene un bot de JavaScript, puede encontrar estos valores en el archivo .env del bot.If you have a JavaScript bot you can find these values in your bot's .env file. Si tiene un bot de C# , puede encontrar estos valores en el archivo appsettings.json.If you have a C# bot you can find these values in the appsettings.json file. Para un bot de Java, puede encontrar estos valores en el archivo application.properties.For a Java bot you can find these values in the application.properties file. Haga clic en Conectar.Click Connect.

  3. Ahora abra otra ventana del emulador.Now open another Emulator window. Esta segunda ventana del emulador funcionará como depurador.This second Emulator window will work as a debugger. Siga las instrucciones que se describen en el paso anterior.Follow the instructions as described in the previous step. Seleccione Open in debug mode (Abrir en modo de depuración) y haga clic en Conectar.Check Open in debug mode and then click Connect.

  4. En este momento verá un comando con un identificador único ( /INSPECT attach <identifier> ) en el emulador de depuración.At this point you will see a command with a unique identifier (/INSPECT attach <identifier>) in your debugging Emulator. Copie el comando completo con el identificador del emulador de depuración y péguelo en el cuadro de chat del primer emulador.Copy the whole command with the identifier from the debugging Emulator and paste it into the chat box of the first Emulator.

    Nota

    Se genera un identificador único cada vez que el emulador se inicia en modo de depuración después de agregar el middleware de inspección en el código del 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. Ahora puede enviar mensajes en el cuadro de chat del primer emulador e inspeccionar los mensajes en el emulador de depuración.Now you can send messages in the chat box of your first Emulator and inspect the messages in the debugging Emulator. Para inspeccionar el estado de los mensajes, haga clic Bot State en el emulador de depuración y despliegue los valores en la ventana JSON derecha.To inspect the state of the messages click Bot State in the debugging Emulator and unfold values on the right JSON window. Verá el estado del bot en el emulador de depuración:You will see the state of your bot in the debugging Emulator:

    estado del bot

Inspección del estado de un bot configurado en AzureInspect the state of a bot configured in Azure

Si desea inspeccionar el estado de un bot configurado en Azure y conectado a canales (como Teams), deberá instalar y ejecutar ngrok.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.

Ejecución de ngrokRun ngrok

En este momento, ha actualizado el emulador a la versión más reciente y ha agregado el middleware de inspección en el código del bot.At this point you have updated your Emulator to the latest version and added the inspection middleware in your bot's code. El siguiente paso consiste en ejecutar ngrok y configurar el bot local en el registro de canales del bot de Azure.The next step is to run ngrok and configure your local bot to your Azure Bot Channels Registration. Antes de ejecutar ngrok, debe ejecutar el bot localmente.Before running ngrok you need to run your bot locally.

Para ejecutar el bot localmente, haga lo siguiente:To run your bot locally do the following:

  1. Vaya a la carpeta del bot en un terminal y configure el registro npm para que use las versiones más recientes.Navigate to your bot's folder in a terminal and set your npm registration to use the latest builds

  2. Ejecute el bot localmente.Run your bot locally. Verá que el bot expone un número de puerto como 3978 .You will see your bot expose a port number like 3978.

  3. Abra otro símbolo del sistema y vaya a la carpeta de proyecto del bot.Open another command prompt and navigate to your bot's project folder. Ejecute el siguiente comando:Run the following command:

    ngrok http 3978
    
  4. ngrok ahora está conectado al bot que se ejecuta localmente.ngrok is now connected to your locally running bot. Copie la dirección IP pública.Copy the public IP address.

    ngrok-success

Actualización de los registros de canales del botUpdate channel registrations for your bot

Ahora que el bot local está conectado a ngrok puede configurarlo en el registro de canales del bot en Azure.Now that your local bot is connected to ngrok you can configure your local bot to your Bot Channels Registration in Azure.

  1. Vaya al registro de canales del bot en Azure.Go to your Bot Channels Registration in Azure. Haga clic en Configuración en el menú de la izquierda y establezca Messaging endpoint (Punto de conexión de la mensajería) en la dirección IP de ngrok.Click Settings on the left menu and set the Messaging endpoint with your ngrok IP. Si es necesario, agregue /api/messages después de la dirección IP.If necessary add /api/messages after the IP address. Por ejemplo, https://e58549b6.ngrok.io/api/messages.For example, https://e58549b6.ngrok.io/api/messages. Seleccione Enable Streaming Endpoint (Habilitar punto de conexión de streaming) y Guardar.Check Enable Streaming Endpoint and Save.

    endpoint

    Sugerencia

    Si Guardar no está habilitado, puede anular la selección de Enable Streaming Endpoint (Habilitar punto de conexión de streaming) y hacer clic en Guardar y, a continuación, seleccionar Enable Streaming Endpoint y hacer clic en Guardar de nuevo.If Save is not enabled, you can uncheck Enable Streaming Endpoint and click Save, then check Enable Streaming Endpoint and click Save again. Asegúrese de que Enable Streaming Endpoint (Habilitar punto de conexión de streaming) está seleccionado y se guardará la configuración del punto de conexión.You need to make sure that Enable Streaming Endpoint is checked and the configuration of the endpoint is saved.

  2. Vaya al grupo de recursos del bot, haga clic en Implementación y seleccione el registro de canales de bot que implementó previamente de manera correcta.Go to your bot's resource group, click Deployment, and select your Bot Channels Registration that previously deployed successfully. Haga clic en Entradas situado a la izquierda y obtenga los valores de appId y appSecret.Click Inputs on the left side to get the appId and appSecret. Actualice el archivo .env del bot (o el archivo appsettings.json si tiene un bot de C#) con los valores de appId y 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. Inicie el emulador, haga clic en Abrir bot y coloque en la dirección URL del http://localhost:3978/api/messages bot.Start your Emulator, click Open Bot, and put http://localhost:3978/api/messages in the Bot URL. Rellene Microsoft App ID (Id. de aplicación de Microsoft) y Microsoft App password (Contraseña de aplicación de Microsoft) con los mismos valores de appId y appSecret que agregó al archivo .env (o appsettings.json) del bot.Fill Microsoft App ID and Microsoft App password with the same appId and appSecret you added to our bot's .env (appsettings.json) file. Haga clic en Conectar.Then click Connect.

  4. El bot en ejecución está conectado ahora al registro de canales de bot en Azure.Your running bot is now connected to your Bot Channels Registration in Azure. Puede probar el chat en web haciendo clic en Test in Web Chat (Probar en chat en web) y enviando mensajes en el cuadro de chat.You can test the web chat by clicking Test in Web Chat and sending messages in the chat box.

    test-web-chat

  5. Ahora vamos a habilitar el modo de depuración en el emulador.Now let's enable the debugging mode in the Emulator. En el emulador, seleccione Depurar > Iniciar depuración.In your Emulator select Debug > Start Debugging. Escriba la dirección IP de ngrok (no olvide agregar /api/messages) para la dirección URL del bot (por ejemplo, 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). En Microsoft App ID (Identificador de aplicación de Microsoft), escriba el identificador de aplicación del bot.For Microsoft App ID, enter your bot's app ID. En Contraseña de aplicación de Microsoft, escriba el secreto de la aplicación del bot.For Microsoft App password, enter your bot's app secret. Asegúrese de que Open in debug mode (Abrir en modo de depuración) también está seleccionado.Make sure Open in debug mode is checked as well. Haga clic en Conectar.Click Connect.

  6. Cuando el modo de depuración está habilitado, se generará un UUID en el emulador.When the debugging mode is enabled a UUID will be generated in your Emulator. Un UUID es un identificador único que se genera cada vez que se inicia el modo de depuración en el emulador.A UUID is a unique ID generated every time you start the debugging mode in your Emulator. Copie y pegue el UUID en el cuadro de chat de Test in Web Chat (Probar en chat en web) del cuadro de chat del canal.Copy and paste the UUID to the Test in Web Chat chat box or your channel's chat box. Aparecerá el mensaje "Attached to session, all traffic is being replicated for inspection" (Conectado a la sesión, todo el tráfico se replicará para su inspección) en el cuadro de chat.You will see the message "Attached to session, all traffic is being replicated for inspection" in the chat box.

Puede empezar a depurar el bot enviando mensajes en el cuadro de chat del canal configurado.You can start debugging your bot by sending messages in the configured channel's chat box. El emulador local actualizará automáticamente los mensajes con todos los detalles para la depuración.Your local Emulator will automatically update the messages with all the details for debugging. Para inspeccionar el estado de los mensajes del bot, haga clic en Bot State y despliegue los valores en la ventana JSON correcta.To inspect your bot's state of messages click Bot State and unfold the values in the right JSON window.

debug-inspection-middleware

Recursos adicionalesAdditional resources