Отладка бота с помощью проверяющего ПО промежуточного слоя

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

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

Мы используем EchoBot, созданный локально с помощью Bot Framework версии 4 в кратком руководстве по созданию бота, чтобы показать, как отлаживать и проверять состояние сообщения бота. Отладку бота также можно выполнять с помощью IDE или Bot Framework Emulator, но для отладки состояния в бота нужно добавить проверяющее ПО промежуточного слоя. Примеры бота проверки доступны для C#, JavaScript, JavaScript и Python.

Примечание.

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

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

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

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

Необходимые компоненты

• Знание по промежуточного слоя бота и управление состоянием
• Знание отладки бота пакета SDK и тестирования и отладки с помощью эмулятора
• Установка эмулятора Bot Framework
• Установка Dev Tunnel (если вы хотите выполнить отладку бота, настроенного в Azure для использования других каналов)
• Копия примера бота проверки для C#, JavaScript, JavaScript или Python

Обновление эмулятора до последней версии

Перед использованием по промежуточного слоя проверки бота для отладки бота обновите эмулятор до версии 4.15 или более поздней. Проверьте последнюю версию на наличие обновлений.

Чтобы проверить версию эмулятора, выберите "Справка", а затем "Сведения " в меню. Вы увидите текущую версию эмулятора.

Изменение кода бота

C#

Состояние проверки и по промежуточному слоям проверки настраиваются в файле Startup.cs , а затем используются адаптером.

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

Обновите класс бота в файле 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++;
}

JavaScript

Перед обновлением кода бота обновите свои пакеты до последних версий, выполнив следующую команду в терминале:

npm install --save botbuilder@latest

Затем нужно обновить код бота JavaScript следующим образом. Дополнительные сведения см. здесь: обновите код бота или ознакомьтесь с примером по промежуточного слоя проверки на GitHub.

index.js

Настройте состояние проверки и добавьте проверяющее ПО промежуточного слоя в адаптер в файле index.js.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

Обновите класс бота в файле bot.js.

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

Настройте состояние проверки и добавьте ПО промежуточного слоя проверки в адаптер в файл Application.java . Состояние проверки устанавливается путем предоставления нового spring @Bean для предоставления BotFrameworkHttpAdapter, который установлен @Primary таким образом, что он переопределит стандартный BotFrameworkHttpAdapter, предоставляемый базовым классом BotDependencyConfiguration. Ознакомьтесь с приведенным ниже обновлением кода или ознакомьтесь с примером по промежуточного слоя проверки на сайте GitHub.

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection реализован в составе пакета com.microsoft.bot.integration и может быть проверен из исходного кода пакета SDK для Java.

Обновите класс бота в файле EchoBot.java .

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Перед обновлением кода бота установите необходимые пакеты PyPI, выполнив следующие команды в терминале:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Настройте состояние проверки в файле app.py, добавив ПО промежуточного слоя в адаптер.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

Обновите класс бота в файле echo_bot.py.

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

Локальное тестирование бота

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

1. Перейдите в каталог бота в терминале и выполните следующую команду, чтобы запустить бот локально:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. Откройте эмулятор. Выберите "Открыть бот". Заполните URL-адрес бота значениями http://localhost:3978/api/messages MicrosoftAppId и MicrosoftAppPassword. Если у вас есть бот JavaScript, эти значения можно найти в env-файле бота. Если у вас есть бот C#, эти значения можно найти в файле appsettings.json . Для бота Java эти значения можно найти в файле application.properties . Нажмите Подключиться.

3. Теперь откройте другое окно эмулятора. Второе окно эмулятора будет работать в качестве отладчика. Следуйте инструкциям, описанным выше. Установите флажок "Открыть в режиме отладки" и нажмите кнопку "Подключить".

4. На этом этапе вы увидите команду с уникальным идентификатором (/INSPECT attach <identifier>) в отладчике эмулятора. Скопируйте всю команду с идентификатором из эмулятора отладки и вставьте ее в окно чата первого эмулятора.

   Примечание.

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

5. Теперь вы можете отправлять сообщения в поле чата первого эмулятора и проверять сообщения в эмуляторе отладки. Чтобы проверить состояние сообщений, выберите "Состояние бота" в эмуляторе отладки и разверните значения в правом окне JSON. Вы увидите состояние бота в эмуляторе отладки:

   

Проверка состояния бота, настроенного в Azure

Если вы хотите проверить состояние бота, настроенного в Azure, и подключиться к каналам (например, Teams), необходимо установить и запустить туннели разработки.

Запуск devtunnel

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

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

1. Перейдите в папку бота в терминале и задайте регистрацию npm, чтобы использовать последние сборки

2. Запустите бот на локальном компьютере. Вы увидите, что бот предоставляет номер порта, например 3978.

3. Откройте другую командную строку и перейдите в папку проекта бота. Выполните следующую команду:

   devtunnel host -a -p 3978
   

4. Devtunnel теперь подключен к локально работающему боту. Скопируйте общедоступный URL-адрес безопасности (HTTPS).

   

Обновление ресурса бота

Теперь, когда локальный бот подключен к devtunnel, вы можете настроить ресурс бота в Azure для использования URL-адреса devtunnel.

1. Перейдите к ресурсу бота в Azure. В меню слева в разделе "Параметры" выберите "Конфигурация".

   1. Задайте для конечной точки обмена сообщениями URL-адрес devtunnel, скопированный вами. При необходимости добавьте /api/messages после IP-адреса. Например, https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Выберите "Включить конечную точку потоковой передачи".

      

   3. Щелкните Применить, чтобы сохранить изменения.

      Совет

      Если применение не включено, можно снять флажок "Включить конечную точку потоковой передачи" и выбрать "Применить", а затем нажмите кнопку "Включить конечную точку потоковой передачи" и снова нажмите кнопку "Применить". Убедитесь, что флажок Включить конечную точку потоковой передачи установлен, а конфигурация конечной точки сохранена.

2. Перейдите в группу ресурсов бота.

   1. Выберите "Развертывание" и выберите ресурс бота, который ранее успешно развернут. Выберите шаблон из меню слева, чтобы получить MicrosoftAppId и MicrosoftAppPassword для веб-приложения, связанного с ботом.

      

   2. Обновите файл конфигурации бота (appsettings.json для C#или .env для JavaScript) с помощью MicrosoftAppId и MicrosoftAppPassword.

3. Запустите эмулятор, выберите "Открыть бот" и введите http://localhost:3978/api/messages URL-адрес бота. Заполните идентификатор приложения Майкрософт и пароль приложения Майкрософт тем же microsoftAppId и MicrosoftAppPassword , которые вы добавили в файл конфигурации нашего бота. В этом случае выберите Подключиться.

4. Запущенный бот теперь подключен к ресурсу бота в Azure. Чтобы протестировать бота в Azure в Веб-чат, перейдите к ресурсам бота, выберите "Тестировать в Веб-чат" и отправьте сообщения боту.

Включение режима отладки

1. В эмуляторе выберите "Отладка" и "Начать отладку".

2. Введите URL-адрес devtunnel (не забудьте добавить /api/messages) для URL-адреса бота (например, https://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Для идентификатора приложения Майкрософт введите идентификатор приложения бота.
   2. Для пароля приложения Microsoft App введите секрет приложения бота.
   3. Также убедитесь, что флажок Открыть в режиме отладки установлен.
   4. Нажмите Подключиться.

3. С включенным режимом отладки эмулятор создает идентификатор UUID. UUID — это уникальный идентификатор, создаваемый при каждом запуске режима отладки в эмуляторе.

4. Скопируйте и вставьте UUID в тест в поле чата Веб-чат для поля чата канала. Вы увидите сообщение "Присоединено к сеансу, весь трафик реплицируется для проверки" в поле чата.

Чтобы начать отладку бота, отправьте сообщения в настроенное поле чата канала. Локальный эмулятор автоматически обновит сообщения со всеми сведениями об отладке. Чтобы проверить состояние сообщений бота, выберите "Состояние бота" и разверните значения в правом окне JSON.

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

• Узнайте, как отладить бота с помощью файлов расшифровки.
• Узнайте, как выполнить отладку навыка или потребителя навыков.