Depurar um bot com middleware de inspeção

APLICA-SE A: SDK v4

Este artigo descreve como depurar um bot usando middleware de inspeção. Esse recurso permite que o Bot Framework Emulator depure o tráfego dentro e fora do bot e veja o estado atual do bot. Você pode usar uma mensagem de rastreamento para enviar dados ao Emulator e inspecionar o estado do bot em qualquer momento da conversa.

Usamos um EchoBot criado localmente usando o Bot Framework v4 Criar um bot para mostrar como depurar e inspecionar o estado da mensagem do bot. Você também pode Depurar um bot usando o IDE ou Depurar com o Bot Framework Emulator, mas, para depurar o estado, você precisa adicionar o middleware de inspeção ao bot. Os exemplos de bot de inspeção estão disponíveis para C#, JavaScript, Java e Python.

Pré-requisitos

• Baixar e instalar o Bot Framework Emulator
• Conhecimento do middleware de bot
• Conhecimento do estado de gerenciamento de bot
• Baixar e instalar o ngrok (se você quiser depurar um bot configurado no Azure para usar canais adicionais)

Atualizar sua Emulator para a versão mais recente

Antes de usar o middleware de inspeção de bot para depurar o bot, atualize o Emulator para a versão 4.5 ou posterior. Verifique a versão mais recente para obter atualizações.

Para verificar a versão do Emulator, selecione Ajuda e, em seguida, Sobre no menu. Você verá a versão atual do seu Emulator.

Atualizar o código do bot

C#

Configure o estado de inspeção e adicione o middleware de inspeção ao adaptador no arquivo Startup.cs. O estado de inspeção é fornecido por injeção de dependência. Consulte a atualização de código abaixo ou consulte o exemplo de middleware de inspeção no GitHub.

Startup.cs

// The Inspection Middleware needs some scratch state to keep track of the (logical) listening connections.
services.AddSingleton<InspectionState>();

// Create the Bot Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithInspection>();

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

Atualize a classe do bot no arquivo 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

Antes de atualizar o código do bot, você deve atualizar os pacotes dele para as versões mais recentes executando o seguinte comando no terminal:

npm install --save botbuilder@latest

Em seguida, você precisa atualizar o código do bot JavaScript conforme descrito a seguir. Você pode ler mais aqui: atualize o código do bot ou consulte o exemplo de middleware de inspeção no GitHub.

index.js

Configure o estado de inspeção e adicione o middleware de inspeção ao adaptador no arquivo index.js.

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

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

const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
    MicrosoftAppId: process.env.MicrosoftAppId,
    MicrosoftAppPassword: process.env.MicrosoftAppPassword,
    MicrosoftAppType: process.env.MicrosoftAppType,
    MicrosoftAppTenantId: process.env.MicrosoftAppTenantId
});

const botFrameworkAuthentication = createBotFrameworkAuthenticationFromConfiguration(null, credentialsFactory);

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

bot.js

Atualize a classe bot no arquivo 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

Configure o estado de inspeção e adicione o middleware de inspeção ao adaptador no arquivo Application.java . O estado de inspeção é definido fornecendo um novo Spring @Bean para fornecer o BotFrameworkHttpAdapter definido como sendo @Primary para que ele substitua o BotFrameworkHttpAdapter padrão fornecido pela classe base BotDependencyConfiguration. Consulte a atualização de código abaixo ou consulte o exemplo de middleware de inspeção no 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 é implementado como parte do pacote com.microsoft.bot.integration e pode ser revisado do código-fonte do SDK do Java.

Atualize a classe de bot no arquivo 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

Antes de atualizar o código do bot, instale os pacotes de PyPI necessários executando os seguintes comandos em um terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Configure o estado de inspeção no arquivo app.py adicionando um middleware ao adaptador.

app.py

from botbuilder.core import (
    BotFrameworkAdapter,
    BotFrameworkAdapterSettings,
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
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.
SETTINGS = BotFrameworkAdapterSettings(CONFIG.APP_ID, CONFIG.APP_PASSWORD)
ADAPTER = BotFrameworkAdapter(SETTINGS)

# Create MemoryStorage and state
MEMORY = MemoryStorage()
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)

Atualize a classe do bot no arquivo 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

Testar o bot localmente

Depois de atualizar o código, você pode executar o bot localmente e testar o recurso de depuração usando dois Emuladores: um para enviar e receber mensagens e outro para inspecionar o estado das mensagens no modo de depuração. Para testar o bot localmente, execute as seguintes etapas:

1. Acesse o diretório do bot em um terminal e execute o seguinte comando para executar o bot localmente:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Abra sua Emulator. Selecione Abrir Bot. Preencha a URL do Bot com http://localhost:3978/api/messages os valores MicrosoftAppId e MicrosoftAppPassword . Se você tiver um bot JavaScript, poderá encontrar esses valores no arquivo .env desse bot. Se você tiver um bot C#, poderá encontrar esses valores no arquivo appsettings.json. Para um bot Java, você pode encontrar esses valores no arquivo application.properties . Selecione Conectar.

3. Agora abra outra janela Emulator. Esta segunda janela Emulator funcionará como um depurador. Siga as instruções descritas na etapa anterior. Verifique Abrir no modo de depuração e selecione Conexão.

4. Neste ponto, você verá um comando com um identificador exclusivo (/INSPECT attach <identifier>) no Emulator de depuração. Copie o comando inteiro com o identificador do Emulador de depuração e cole-o na caixa de chat do primeiro Emulador.

   Observação

   Um identificador exclusivo é gerado sempre que o Emulator é iniciado no modo de depuração depois que você adiciona o middleware de inspeção no código do bot.

5. Agora você pode enviar mensagens na caixa de chat do seu primeiro Emulator e inspecionar as mensagens no Emulator de depuração. Para inspecionar o estado das mensagens, selecione Estado do Bot na Emulator de depuração e desdobre valores na janela JSON direita. Você verá o estado do bot na Emulator de depuração:

   

Inspecionar o estado de um bot configurado no Azure

Se você quiser inspecionar o estado do bot configurado no Azure e conectado a canais (como Teams), será necessário instalar e executar o ngrok.

Executar o ngrok

Neste ponto, você atualizou sua Emulator para a versão mais recente e adicionou o middleware de inspeção no código do bot. A próxima etapa é executar o ngrok e configurar o bot local. Antes de executar o ngrok, você precisa executar o bot localmente.

Para executar o bot localmente, faça o seguinte:

1. Vá para a pasta do bot em um terminal e defina seu registro npm para usar os builds mais recentes

2. Execute o bot localmente. Você verá seu bot expor um número de porta como 3978.

3. Abra outro prompt de comando e vá para a pasta de projeto do bot. Execute o comando a seguir:

   ngrok http 3978
   

4. O ngrok agora está conectado ao bot executado localmente. Copie o endereço IP público seguro (HTTPS).

   

Atualizar o recurso do bot

Agora que o bot local está conectado ao ngrok, você pode configurar o recurso de bot no Azure para usar a URL do ngrok.

1. Vá para o recurso de bot no Azure. No menu à esquerda, em Configurações, selecione Configuração.

   1. Defina o ponto de extremidade de Mensagens como o endereço IP do ngrok copiado. Se necessário, adicione /api/messages após o endereço IP. Por exemplo, https://e58549b6.ngrok.io/api/messages.

   2. Selecione Habilitar Ponto de Extremidade de Streaming.

      

   3. Selecione Aplicar para salvar as alterações.

      Dica

      Se Aplicar não estiver habilitado, você poderá desmarcar Habilitar Ponto de Extremidade de Streaming e selecionar Aplicar e, em seguida, verificar Habilitar Ponto de Extremidade de Streaming e selecionar Aplicar novamente. Você precisa verificar se Habilitar Ponto de Extremidade de Streaming está marcado e a configuração do ponto de extremidade foi salva.

2. Vá para o grupo de recursos do bot.

   1. Selecione Implantação e selecione o recurso de bot que foi implantado com êxito. Selecione Modelo no menu à esquerda para obter o MicrosoftAppId e o MicrosoftAppPassword para o aplicativo Web associado ao bot.

      

   2. Atualize o arquivo de configuração do bot (appsettings.json para C#ou .env para JavaScript) com o MicrosoftAppId e o MicrosoftAppPassword.

3. Inicie seu Emulator, selecione Abrir Bot e insira http://localhost:3978/api/messages na URL do Bot. Preencha a ID de Aplicativo da Microsoft e a senha do Aplicativo Microsoft com o mesmo MicrosoftAppId e MicrosoftAppPassword que você adicionou ao arquivo de configuração do bot. Depois, selecione Conectar.

4. Seu bot em execução agora está conectado ao recurso de bot no Azure. Para testar o bot no Azure no Webchat, acesse os recursos do bot, selecione Testar em Webchat e envie mensagens para o bot.

Habilitar o modo de depuração

1. Em seu Emulator, selecione Depurar e, em seguida, Inicie a Depuração.

2. Insira o endereço IP ngrok (não se esqueça de adicionar /api/mensagens) para a URL do Bot (por exemplo, https://e58549b6.ngrok.io/api/messages).

   1. Para a ID do Aplicativo da Microsoft, insira a ID do aplicativo do bot.
   2. Para senha do Aplicativo Microsoft, insira o segredo do aplicativo do bot.
   3. Verifique se a opção Abrir no modo de depuração também está marcada.
   4. Selecione Conectar.

3. Com o modo de depuração habilitado, o Emulator gera uma UUID. Uma UUID é uma ID exclusiva gerada sempre que você inicia o modo de depuração em seu Emulator.

4. Copie e cole a UUID no Teste na caixa de chat Webchat para a caixa de chat do canal. Você verá a mensagem "Anexado à sessão, todo o tráfego está sendo replicado para inspeção" na caixa de chat.

Você pode iniciar a depuração do bot enviando mensagens na caixa de chat do canal configurado. O Emulator local atualizará automaticamente as mensagens com todos os detalhes para depuração. Para inspecionar o estado das mensagens do bot, selecione Estado do Bot e desdobre os valores na janela JSON certa.

Recursos adicionais

• Experimente o exemplo de bot de middleware de inspeção em C#, JavaScript ou Python .
• Leia solucionar problemas gerais e outros artigos de solução de problemas nesta seção.
• Leia o artigo de instruções Depurar com o Emulador.