Добавление действий трассировки в бот

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Действием трассировки называется действие, которое бот может отправить в Bot Framework Emulator. Вы можете использовать действия трассировки для интерактивной отладки бота, так как они позволяют просматривать сведения о боте при локальном выполнении.

Действия трассировки отправляются только в приложение Emulator, но не другим клиентам и не в каналы. Приложение отображает их в журнале, но не на главной панели разговора.

• Действия трассировки из контекста шага отправляются через обработчики действий отправки, которые зарегистрированы в контексте этого шага.
• Действия трассировки из контекста шага привязываются к входящему действию путем применения ссылки на беседу, если таковая имеется. Для упреждающего сообщения идентификатор адреса для ответа будет содержать новый уникальный идентификатор.
• Независимо от способа отправки действие трассировки никогда не задает флаг ответа .

Примечание.

Пакеты SDK для JavaScript, C# и Python для Bot Framework по-прежнему будут поддерживаться, однако пакет SDK java отменяется с окончательной долгосрочной поддержкой, заканчивающейся в ноябре 2023 года.

Существующие боты, созданные с помощью пакета SDK для Java, будут продолжать функционировать.

Для создания нового бота рекомендуется использовать Microsoft Copilot Studio и ознакомиться с выбором подходящего решения copilot.

Дополнительные сведения см. в статье "Будущее создания бота".

Использование действия трассировки

Чтобы увидеть действие трассировки в приложении Emulator, создайте сценарий, в котором бот отправляет такое действие трассировки. Например, можно создать исключение и отправить действие трассировки из обработчика ошибок на шаге адаптера.

Чтобы отправить из бота действие трассировки, сделайте следующее.

1. Создайте новое действие.
   • Задайте для свойства требуемого типа значение trace.
   • При необходимости задайте для трассировки его имя, метку, значение и тип значения.
2. Чтобы отправить действие трассировки, используйте действие отправки из объекта контекста шага.
   • Этот метод добавляет значения для незаполненных обязательных свойств действия, используя сведения о входящем действии. К этим свойствам относятся идентификатор канала, URL-адрес службы, из и свойства получателя .

Чтобы просмотреть действие трассировки в приложении Emulator, выполните следующие действия.

1. Запустите бота на локальном компьютере.
2. Выполните тестирование в Emulator.
   • Напишите что-нибудь боту, чтобы сработали те шаги в сценарии, которые создают действие трассировки.
   • Когда бот создаст действие трассировки, оно отобразится в журнале Emulator.

Ниже приведено действие трассировки, которое можно увидеть, если вы запустили бот Core, не настроив база знаний QnAMaker, на которые используется бот.

Добавление действия трассировки в обработчик ошибок адаптера

Обработчик ошибок шага адаптера перехватывает все неперехваченные в другом месте исключения, которые создаются ботом во время выполнения. Обработчик ошибок является хорошим местом для действия трассировки, так как вы можете отправить пользователю понятное сообщение и отправить отладочную информацию об исключении эмулятору.

В этом случае используется код из примера Core Bot. Полный пример см. в C#, JavaScript, Python или Java.

C#

Обработчик адаптера OnTurnError создает действие трассировки, которое собирает сведения об исключении и отправляет их в эмулятор.

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

Обработчик адаптера onTurnError создает действие трассировки, которое собирает сведения об исключении и отправляет их в 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

В пакете SDK для Java класс входит в пакет SDK AdapterWithErrorHandler com.microsoft.bot.integration. Обработчик адаптера onTurnError создает действие трассировки, которое собирает сведения об исключении и отправляет их в Emulator. Исходный код адаптера по умолчанию показан ниже.

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

Обработчик адаптера on_error создает действие трассировки, которое собирает сведения об исключении и отправляет их в 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)

Следующие шаги

• В статье Отладка бота с помощью проверяющего ПО промежуточного слоя описывается, как добавить ПО промежуточного слоя для создания действий трассировки.
• Для отладки развернутого робота можно применить Application Insights. Дополнительные сведения см. в статье о добавлении телеметрии в бот.
• Дополнительные сведения о типах действий см. в статье о схеме действий Bot Framework.