Depuración de un bot con middleware de inspección

SE APLICA A: SDK v4

En este artículo se describe cómo depurar un bot mediante middleware de inspección. 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. 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.

Se usa un EchoBot compilado localmente mediante Bot Framework v4 en el inicio rápido Crear un bot para mostrar cómo depurar e inspeccionar el estado del mensaje del bot. 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. Los ejemplos de bots de inspección están disponibles para C#, JavaScript, Java y Python.

Nota:

Los SDK de JavaScript, C# y Python de Bot Framework seguirán siendo compatibles, pero el SDK de Java se va a retirar con la compatibilidad final a largo plazo que finaliza en noviembre de 2023. Solo se realizarán correcciones críticas de seguridad y errores dentro de este repositorio.

Los bots existentes creados con el SDK de Java seguirán funcionando.

Para la creación de nuevos bots, considera el uso de Power Virtual Agents y lee sobre cómo elegir la solución de bot de chat adecuada.

Para obtener más información, consulta El futuro de la creación de bots.

Requisitos previos

Actualización del emulador a la versión más reciente

Antes de usar el middleware de inspección de bot para depurar el bot, debe actualizar el emulador a la versión 4.5 o posterior. Compruebe la versión más reciente para buscar actualizaciones.

Para comprobar la versión del Emulator, seleccione Ayuda, y a continuación, Acerca de en el menú. Aparecerá la versión actual del Emulator.

Actualización del código del bot

El estado de inspección y el middleware de inspección se configuran en el archivo Startup.cs y después son utilizados por el adaptador.

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");
            };
        }

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

Prueba local del bot

Después de actualizar el código, puede ejecutar el bot localmente y probar la característica de depuración con dos emuladores: uno para enviar y recibir mensajes, y el otro para inspeccionar el estado de los mensajes en el modo de depuración. Para realizar la prueba local del bot

  1. Vaya al directorio del bot en un terminal y ejecute el siguiente comando para ejecutar el bot localmente:

    dotnet run
    
  2. Abra el emulador. Seleccione Abrir bot. Rellene la URL del bot con http://localhost:3978/api/messages y los valores MicrosoftAppId y MicrosoftAppPassword. Si tiene un bot de JavaScript, puede encontrar estos valores en el archivo .env del bot. Si tiene un bot de C# , puede encontrar estos valores en el archivo appsettings.json. Para un bot de Java, puede encontrar estos valores en el archivo application.properties . Seleccione Conectar.

  3. Ahora abra otra ventana de Emulator. Esta segunda ventana de Emulator funcionará como un depurador. Siga las instrucciones que se describen en el paso anterior. Seleccione Abrir en modo de depuración y haga clic en Conectar.

  4. En este momento, verá un comando con un identificador único (/INSPECT attach <identifier>) en el Emulator de depuración. Copie el comando completo con el identificador del emulador de depuración y péguelo en el cuadro de chat del primer emulador.

    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 al código del bot.

  5. Ahora puede enviar mensajes en el cuadro de chat del primer emulador e inspeccionar los mensajes en el emulador de depuración. Para inspeccionar el estado de los mensajes, haga clic en Bot State en el Emulator de depuración y despliegue los valores en la ventana JSON situada a la derecha. Verá el estado del bot en el Emulator de depuración:

    bot state

Inspección del estado de un bot configurado en Azure

Si desea inspeccionar el estado de un bot configurado en Azure y conectado a canales (como Teams), deberá instalar y ejecutar ngrok.

Ejecución de ngrok

En este punto, ha actualizado el Emulator a la versión más reciente y ha agregado el middleware de inspección al código del bot. El siguiente paso consiste en ejecutar ngrok y configurar el bot local Antes de ejecutar ngrok, debe ejecutar el bot localmente.

Para la ejecución local del bot:

  1. Vaya a la carpeta del bot en un terminal y configure el registro npm para que utilice las versiones más recientes.

  2. Ejecute el bot localmente. Verá que el bot expone un número de puerto como 3978.

  3. Abra otro símbolo del sistema y vaya a la carpeta de proyecto del bot. Ejecute el siguiente comando:

    ngrok http 3978
    
  4. ngrok ahora está conectado al bot que se ejecuta localmente. Copie la dirección IP pública segura (HTTPS).

    ngrok success

Actualización de un recurso de bot

Ahora que el bot local está conectado a ngrok, puede configurar el recurso de bot en Azure para usar la dirección URL de ngrok.

  1. Vaya al recurso de bot en Azure. Seleccione Configuración en Configuración en el menú de la izquierda.

    1. Establezca el punto de conexión de mensajería en la dirección IP ngrok que copió. Si es necesario, agregue /api/messages después de la dirección IP. Por ejemplo, https://e58549b6.ngrok.io/api/messages.

    2. Seleccione Habilitar punto de conexión de streaming.

      Set endpoint

    3. Seleccione Aplicar para guardar los cambios.

      Sugerencia

      Si Aplicar no está habilitado, puede desactivar Habilitar punto de conexión de streaming y hacer clic en Aplicar y, a continuación, seleccionar Habilitar punto de conexión de streaming y hacer clic en Aplicar de nuevo. 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.

  2. Vaya al grupo de recursos de bot.

    1. Seleccione Implementación y, a continuación, seleccione el recurso de bot que se implementó correctamente. Seleccione Plantilla en el menú de la izquierda para obtener MicrosoftAppId y MicrosoftAppPassword para la aplicación web asociada al bot.

      Get inputs

    2. Actualice el archivo de configuración del bot (appsettings.json para C#, o .env para JavaScript) con MicrosoftAppId y MicrosoftAppPassword.

  3. Inicie el Emulator, haga clic en Abrir bot e introduzca http://localhost:3978/api/messages en la dirección URL del bot. Rellene el identificador de aplicación de Microsoft y la contraseña de la aplicación de Microsoft con el mismo MicrosoftAppId y MicrosoftAppPassword que agregó al archivo de configuración del bot. A continuación, seleccione Conectar.

  4. El bot en ejecución está ahora conectado a su recurso de bot en Azure. Para probar el bot en Azure en Chat en web, vaya a los recursos del bot, seleccione Probar en Chat en web y envíe mensajes al bot.

Habilite el modo de depuración

  1. En el Emulator, seleccione Depurar, y después Iniciar depuración.

  2. Introduzca la dirección IP de ngrok (no olvide añadir /api/messages) en la dirección URL de bot (por ejemplo, https://e58549b6.ngrok.io/api/messages).

    1. Para el identificador de aplicación de Microsoft, introduzca el identificador de aplicación del bot.
    2. En Contraseña de aplicación de Microsoft, escriba el secreto de la aplicación del bot.
    3. Asegúrese de que Open in debug mode (Abrir en modo de depuración) también está seleccionado.
    4. Seleccione Conectar.
  3. Con el modo de depuración habilitado, el emulador genera un UUID. Un UUID es un identificador único que se genera cada vez que se inicia el modo de depuración en el emulador.

  4. Copie y pegue el UUID en el cuadro de chat Probar en chat en web del cuadro de chat del canal. Verá 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.

Puede empezar a depurar el bot enviando mensajes en el cuadro de chat del canal configurado. El emulador local actualizará automáticamente los mensajes con todos los detalles de la depuración. Para inspeccionar el estado de los mensajes del bot, haga clic en Bot State y despliegue los valores en la ventana JSON correcta.

debug-inspection-middleware

Pasos siguientes