검사 미들웨어를 사용하여 봇 디버그

적용 대상: SDK v4

이 문서에서는 검사 미들웨어를 사용하여 봇을 디버그하는 방법을 설명합니다. 이 기능을 사용하면 Bot Framework Emulator가 봇 안팎으로 트래픽을 디버그하고 봇의 현재 상태를 볼 수 있습니다. 추적 메시지를 사용하여 에뮬레이터로 데이터를 보낸 다음, 대화의 지정된 순서에서 봇의 상태를 검사할 수 있습니다.

봇 만들기 빠른 시작에서 Bot Framework v4를 사용하여 로컬로 빌드된 EchoBot을 사용하여 봇의 메시지 상태를 디버그하고 검사하는 방법을 보여 드립니다. Bot Framework Emulator에서 IDE 또는 디버그를 사용하여 봇을 디버그할 수도 있지만 상태를 디버그하려면 검사 미들웨어를 봇에 추가해야 합니다. 검사 봇 샘플은 C#, JavaScript, Java 및 Python에 사용할 수 있습니다.

참고 항목

Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.

Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.

새 봇 빌드의 경우 Microsoft Copilot Studio를 사용하고 올바른 부조종사 솔루션 선택에 대해 알아봅니다.

자세한 내용은 봇 빌드의 미래를 참조 하세요.

필수 조건

• 봇 미들웨어 및 관리 상태에 대한 지식
• SDK 우선 봇을 디버그하고 에뮬레이터를 사용하여 테스트 및 디버그하는 방법에 대한 지식
• Bot Framework Emulator 설치
• 개발자 터널 설치(다른 채널을 사용하도록 Azure에서 구성된 봇을 디버그하려는 경우)
• C#, JavaScript, Java 또는 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 파일의 어댑터에 검사 미들웨어를 추가합니다. 검사 상태는 BotFrameworkHttpAdapter를 제공하는 새 Spring @Bean 을 제공하여 설정 @Primary 되므로 BotDependencyConfiguration 기본 클래스에서 제공하는 기본 BotFrameworkHttpAdapter를 재정의합니다. 아래 코드 업데이트를 참조하거나 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 패키지의 일부로 구현되며 Java SDK 소스 코드에서 검토할 수 있습니다.

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)에 연결된 봇의 상태를 검사하려면 Dev Tunnels를 설치하고 실행해야 합니다.

devtunnel 실행

이 시점에서 에뮬레이터를 최신 버전으로 업데이트하고 봇 코드에 검사 미들웨어를 추가했습니다. 다음 단계는 devtunnel을 실행하고 로컬 봇을 구성하는 것입니다. devtunnel을 실행하기 전에 봇을 로컬로 실행해야 합니다.

봇을 로컬로 실행하려면 다음을 수행합니다.

1. 터미널에서 봇의 폴더로 이동하여 최신 빌드를 사용하도록 npm 등록을 설정합니다.

2. 로컬로 봇을 실행합니다. 봇이 다음과 같은 포트 번호를 노출하는 것을 볼 수 있습니다 3978.

3. 다른 명령 프롬프트를 열고 봇의 프로젝트 폴더로 이동합니다. 다음 명령을 실행합니다.

   devtunnel host -a -p 3978
   

4. 이제 devtunnel이 로컬로 실행되는 봇에 연결됩니다. 보안(HTTPS) 공용 URL을 복사합니다.

   

봇 리소스 업데이트

이제 로컬 봇이 devtunnel에 연결되었으므로 Azure에서 devtunnel URL을 사용하도록 봇 리소스를 구성할 수 있습니다.

1. Azure에서 봇 리소스로 이동합니다. 왼쪽 메뉴의 설정에서 구성을 선택합니다.

   1. 메시징 엔드포인트를 복사한 devtunnel URL 주소로 설정합니다. 필요한 경우 IP 주소 뒤 /api/messages를 추가합니다. 예들 들어 https://0qg12llz-3978.usw2.devtunnels.ms/api/messages입니다.

   2. 스트리밍 엔드포인트 사용을 선택합니다.

      

   3. 적용을 선택하여 변경 내용을 저장합니다.

      팁

      적용을 사용하도록 설정하지 않은 경우 스트리밍 엔드포인트 사용의 선택을 취소하고 적용을 선택한 다음 스트리밍 엔드포인트 사용을 선택하고 다시 적용을 선택할 수 있습니다. 스트리밍 엔드포인트 사용이 선택되고 엔드포인트 구성이 저장되었는지 확인해야 합니다.

2. 봇의 리소스 그룹으로 이동합니다.

   1. 배포를 선택한 다음, 이전에 성공적으로 배포된 봇 리소스를 선택합니다. 왼쪽 메뉴에서 템플릿을 선택하여 봇과 연결된 웹앱에 대한 MicrosoftAppId 및 MicrosoftAppPassword를 가져옵니다.

      

   2. MicrosoftAppId 및 MicrosoftAppPassword를 사용하여 봇의 구성 파일(C#의 경우 appsettings.json 또는 JavaScript용 .env)을 업데이트합니다.

3. 에뮬레이터를 시작하고, 봇 열기를 선택하고, 봇 URL에 입력 http://localhost:3978/api/messages 합니다. Microsoft 앱 ID 및 Microsoft 앱 암호를 봇의 구성 파일에 추가한 것과 동일한 MicrosoftAppId 및 MicrosoftAppPassword로 채웁니다. 그런 다음 연결을 선택합니다.

4. 이제 실행 중인 봇이 Azure의 봇 리소스에 연결됩니다. 웹 채팅 Azure에서 봇을 테스트하려면 봇 리소스로 이동하여 웹 채팅 테스트를 선택하고 봇에 메시지를 보냅니다.

디버깅 모드 사용

1. 에뮬레이터에서 디버그를 선택한 다음 디버깅을 시작합니다.

2. 봇 URL(예https://4jj51x75-51865.usw2.devtunnels.ms/api/messages: )에 대한 devtunnel URL(/api/messages를 추가하는 것을 잊지 마세요)을 입력합니다.

   1. Microsoft 앱 ID의 경우 봇의 앱 ID를 입력합니다.
   2. Microsoft 앱 암호의 경우 봇의 앱 비밀을 입력합니다.
   3. 디버그 모드에서 열기도 선택되어 있는지 확인합니다.
   4. 연결을 선택합니다.

3. 디버깅 모드를 사용하도록 설정하면 에뮬레이터가 UUID를 생성합니다. UUID는 에뮬레이터에서 디버깅 모드를 시작할 때마다 생성되는 고유 ID입니다.

4. UUID를 복사하여 채널의 채팅 상자에 대한 웹 채팅 채팅 상자의 테스트에 붙여넣습니다. 채팅 상자에 "세션에 연결되고 모든 트래픽이 검사를 위해 복제되고 있습니다"라는 메시지가 표시됩니다.

구성된 채널의 채팅 상자에서 메시지를 전송하여 봇 디버깅을 시작할 수 있습니다. 로컬 에뮬레이터는 디버깅에 대한 모든 세부 정보로 메시지를 자동으로 업데이트합니다. 봇의 메시지 상태를 검사하려면 봇 상태를 선택하고 오른쪽 JSON 창에서 값을 펼냅니다.

다음 단계

• 기록 파일을 사용하여 봇을 디버그하는 방법을 알아봅니다.
• 기술 또는 기술 소비자를 디버그하는 방법을 알아봅니다.