Aggiungere attività di traccia al bot

SI APPLICA A: SDK v4

Un'attività di traccia è un'attività che il bot può inviare a Bot Framework Emulator. È possibile usare le attività di traccia per eseguire il debug interattivo di un bot, perché consentono di visualizzare informazioni sul bot mentre viene eseguito in locale.

Le attività di traccia vengono inviate solo a Emulator e non a qualsiasi altro client o canale. Emulator le visualizza nel log, ma non nel pannello principale della chat.

• Le attività di traccia inviate tramite il contesto del turno vengono inviate tramite i gestori on send activity registrati nel contesto stesso.
• Le attività di traccia inviate tramite il contesto del turno vengono associate all'attività in ingresso, applicando il riferimento alla conversazione, se presente. Per un messaggio proattivo il valore di reply to ID sarà un nuovo GUID.
• Indipendentemente dalla modalità di invio, un'attività di traccia non imposta mai il flag di risposta .

Nota

Gli SDK JavaScript, C# e Python di Bot Framework continueranno a essere supportati, ma Java SDK verrà ritirato con il supporto finale a lungo termine che termina a novembre 2023.

I bot esistenti creati con Java SDK continueranno a funzionare.

Per la creazione di nuovi bot, prendere in considerazione l'uso di Power Virtual Agents e leggere la scelta della soluzione chatbot appropriata.

Per altre informazioni, vedere Il futuro della compilazione di bot.

Per usare un'attività di traccia

Per usare un'attività di traccia in Emulator, è necessario uno scenario in cui il bot invia un'attività di traccia, ad esempio la generazione di un'eccezione e l'invio di un'attività di traccia dal gestore on turn error dell'adapter.

Per inviare un'attività di traccia dal bot:

1. Creare una nuova attività.
   • Impostare la proprietà del tipo richiesto su "trace".
   • Facoltativamente, impostarne le proprietà name, label, value e value type, in base alle esigenze della traccia.
2. Usare il metodo send activity dell'oggetto turn context per inviare l'attività di traccia.
   • Questo metodo aggiunge i valori per le proprietà obbligatorie rimanenti dell'attività, in base all'attività in ingresso. Queste proprietà includono l'ID canale, l'URL del servizio, le proprietà e i destinatari.

Per visualizzare un'attività di traccia in Emulator:

1. Eseguire il bot in locale nel computer.
2. Testare il bot con Emulator.
   • Interagire con il bot e usare i passaggi dello scenario per generare l'attività di traccia.
   • Quando il bot genera l'attività di traccia, questa viene visualizzata nel log di Emulator.

Ecco un'attività di traccia su cui si potrebbe vedere se è stato eseguito il bot Core senza prima configurare la knowledge base QnAMaker su cui si basa il bot.

Aggiungere un'attività di traccia al gestore on turn error dell'adapter

Il gestore on turn error dell'adapter rileva qualsiasi eccezione altrimenti non rilevata generata dal bot durante un turno. Il gestore degli errori è un buon punto di riferimento per un'attività di traccia, in quanto è possibile inviare un messaggio descrittivo all'utente e inviare informazioni di debug sull'eccezione all'emulatore.

Questo codice di esempio è tratto dall'esempio del bot di base. Vedere l'esempio completo in C#, JavaScript, Python o Java.

C#

Il gestore OnTurnError dell'adapter crea l'attività di traccia per includere le informazioni sull'eccezione e la invia a Emulator.

AdapterWithErrorHandler.cs

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

JavaScript

Il gestore onTurnError dell'adapter crea l'attività di traccia per includere le informazioni sull'eccezione e la invia a Emulator.

index.js

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    let onTurnErrorMessage = 'The bot encountered an error or bug.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    // Clear out state
    await conversationState.delete(context);
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Define a state store for your bot. See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
// A bot requires a state store to persist the dialog and user state between messages.

// For local development, in-memory storage is used.

Java

In Java SDK, una AdapterWithErrorHandler classe è inclusa nell'SDK nel pacchetto com.microsoft.bot.integration . Il gestore onTurnError dell'adapter crea l'attività di traccia per includere le informazioni sull'eccezione e la invia a Emulator. Di seguito è riportato il codice sorgente per l'adattatore predefinito.

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // 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.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

Il gestore on-error dell'adapter crea l'attività di traccia per includere le informazioni sull'eccezione e la invia a Emulator.

adapter_with_error_handler.py

# This check writes out errors to console log
# NOTE: In production environment, you should consider logging this to Azure
#       application insights.
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
traceback.print_exc()

# Send a message to the user
await context.send_activity("The bot encountered an error or bug.")
await context.send_activity(
    "To continue to run this bot, please fix the bot source code."
)
# Send a trace activity if we're talking to the Bot Framework Emulator
if context.activity.channel_id == "emulator":
    # Create a trace activity that contains the error object
    trace_activity = Activity(
        label="TurnError",
        name="on_turn_error Trace",
        timestamp=datetime.utcnow(),
        type=ActivityTypes.trace,
        value=f"{error}",
        value_type="https://www.botframework.com/schemas/error",
    )
    # Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.send_activity(trace_activity)

Passaggi successivi

• Eseguire il debug di un bot con il middleware di ispezione descrive come aggiungere middleware che genera attività di traccia.
• Per eseguire il debug di un bot distribuito, è possibile usare Application Insights. Per altre informazioni, vedere Aggiungere dati di telemetria al bot.
• Per informazioni dettagliate sui singoli tipi di attività, vedere lo schema delle attività di Bot Framework.