Incorporación de actividades de seguimiento al botAdd trace activities to your bot

se aplica a: SDK V4APPLIES TO: SDK v4

Una actividad de seguimiento es una actividad que el bot puede enviar a Bot Framework Emulator.A trace activity is an activity that your bot can send to the Bot Framework Emulator. Puede usar las actividades de seguimiento para depurar un bot de forma interactiva, ya que permiten ver información sobre el bot mientras se ejecuta localmente.You can use trace activities to interactively debug a bot, as they allow you to view information about your bot while it runs locally.

Las actividades de seguimiento solo se envían al emulador y no a ningún otro cliente o canal.Trace activities are sent only to the Emulator and not to any other client or channel. El emulador las muestra en el registro, pero no en el panel principal de chats.The Emulator displays them in the log but not the main chat panel.

  • Las actividades de seguimiento enviadas mediante el contexto del turno se envían a través de los controladores de actividad de envío registrados en el contexto del turno.Trace activities sent via the turn context are sent through the send activity handlers registered on the turn context.
  • Las actividades de seguimiento enviadas mediante el contexto del turno se asocian a la actividad de entrada aplicando la referencia de la conversación, en caso de que haya alguna.Trace activities sent via the turn context are associated with the inbound activity, by applying the conversation reference, if there was one. En el caso de un mensaje proactivo, el identificador Responder a será un nuevo GUID.For a proactive message, the reply to ID will be a new GUID.
  • Independientemente de cómo se envíe, una actividad de seguimiento nunca establece la marca responded.Regardless of how it is sent, a trace activity never sets the responded flag.

Para utilizar una actividad de seguimientoTo use a trace activity

Para ver una actividad de seguimiento en el emulador, necesita un escenario en el que el bot enviará una actividad de seguimiento, como generar una excepción y enviar una actividad de seguimiento desde el controlador de errores del turno del adaptador.In order to see a trace activity in the Emulator, you need a scenario in which your bot will send a trace activity, such as throwing an exception and sending a trace activity from the adapter's on turn error handler.

Para enviar una actividad de seguimiento desde el bot:To send a trace activity from your bot:

  1. Cree una nueva actividad.Create a new activity.
    • Establezca su propiedad type en "trace".Set its type property to "trace". Este es un paso necesario.This is required.
    • Opcionalmente, puede establecer sus propiedades name, label, value y value type, según corresponda para el seguimiento.Optionally set its name, label, value, and value type properties, as appropriate for the trace.
  2. Use el método send activity del objeto del contexto del turno para enviar la actividad de seguimiento.Use the turn context object's send activity method to send the trace activity.
    • Este método agrega los valores de las restantes propiedades necesarias de la actividad, en función de la actividad de entrada.This method adds values for the remaining required properties of the activity, based on the incoming activity. Entre ellas se incluyen las propiedades channel ID, service URL, from y recipient.These include the channel ID, service URL, from, and recipient properties.

Para ver una actividad de seguimiento en el emulador:To view a trace activity in the Emulator:

  1. Ejecute el ejemplo localmente en la máquina.Run the bot locally on your machine.
  2. Pruébelo con el emulador.Test it using the Emulator.
    • Interactúe con el bot y siga los pasos del escenario para generar la actividad de seguimiento.Interact with the bot and use the steps in your scenario to generate the trace activity.
    • Cuando el bot emite la actividad de seguimiento, la actividad de seguimiento se muestra en el registro del emulador.When your bot emits the trace activity, the trace activity is displayed in the Emulator log.

Esta es una actividad de seguimiento que puede ver si ejecutó el bot básico sin configurar primero la base de conocimiento de QnAMaker en la que se basa el bot.Here is a trace activity you might see if you ran the Core bot without first setting up the QnAMaker knowledge base that the bot relies upon.

Captura de pantalla del emulador

Incorporación de una actividad de seguimiento al controlador de errores del adaptadorAdd a trace activity to the adapter's on-error handler

El controlador de errores del turno del adaptador captura cualquier excepción no detectada de otro modo que se produzca en el bot durante un turno.The adapter's on turn error handler catches any otherwise uncaught exception thrown from the bot during a turn. Este es un buen lugar para una actividad de seguimiento, ya que puede enviar un mensaje descriptivo al usuario y enviar información de depuración sobre la excepción al emulador.This is a good place for a trace activity, as you can send a user-friendly message to the user and send debugging information about the exception to the Emulator.

Este código de ejemplo procede del ejemplo Bot básico.This example code is from the Core Bot sample. Puede ver el ejemplo completo en C#, JavaScript o Python.See the complete sample in C# or JavaScript or Python. Para Java, el código siguiente es del código del SDK de Java.For Java the code below is from the SDK code Java.

El controlador OnTurnError del adaptador crea la actividad de seguimiento para incluir la información de la excepción y la envía al emulador.The adapter's OnTurnError handler creates the trace activity to include the exception information and sends it to the Emulator.

AdapterWithErrorHandler.csAdapterWithErrorHandler.cs

OnTurnError = async (turnContext, exception) =>
{
    // Log any leaked exception from the application.
    // NOTE: In production environment, you should consider logging this to
    // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
    // to add telemetry capture to your bot.
    logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

    // Send a message to the user
    var errorMessageText = "The bot encountered an error or bug.";
    var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
    await turnContext.SendActivityAsync(errorMessage);

    errorMessageText = "To continue to run this bot, please fix the bot source code.";
    errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
    await turnContext.SendActivityAsync(errorMessage);

    if (conversationState != null)
    {
        try
        {
            // Delete the conversationState for the current conversation to prevent the
            // bot from getting stuck in a error-loop caused by being in a bad state.
            // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
            await conversationState.DeleteAsync(turnContext);
        }
        catch (Exception e)
        {
            logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
        }
    }

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

Recursos adicionalesAdditional resources