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 de entrada e saída do bot e veja o estado atual do bot. Você pode usar uma mensagem de rastreamento para enviar dados para o emulador e, em seguida, inspecionar o estado do seu bot em qualquer turno da conversa.
Usamos um EchoBot construído localmente usando o Bot Framework v4 no guia de início rápido Criar um bot para mostrar como depurar e inspecionar o estado da mensagem do bot. Você também pode Depurar um bot usando IDE ou Depurar com o Bot Framework Emulator, mas para depurar o estado você precisa adicionar middleware de inspeção ao seu bot. Os exemplos do bot de inspeção estão disponíveis para C#, JavaScript, Java e Python.
Nota
Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o Java SDK está sendo desativado com suporte final de longo prazo terminando em novembro de 2023.
Os bots existentes construídos com o Java SDK continuarão a funcionar.
Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copilot certa.
Para obter mais informações, consulte O futuro da criação de bots.
- Conhecimento de middleware de bot e gerenciamento de estado
- Conhecimento de como depurar um bot SDK-first e testar e depurar com o emulador
- Uma instalação do Bot Framework Emulator
- Um túnel de desenvolvimento de instalação (se você quiser depurar um bot configurado no Azure para usar outros canais)
- Uma cópia do exemplo de bot de inspeção para C#, JavaScript, Java ou Python
Antes de usar o middleware de inspeção de bot para depurar seu bot, atualize seu emulador para a versão 4.15 ou posterior. Verifique se há atualizações na versão mais recente.
Para verificar a versão do seu emulador, selecione Ajuda e, em seguida , Sobre no menu. Você verá a versão atual do seu emulador.
O estado de inspeção e o middleware de inspeção são configurados no arquivo de Startup.cs e, em seguida, usados pelo adaptador.
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");
};
}
Atualize a classe 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++;
}
Depois de atualizar o código, você pode executar seu 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 seu bot localmente:
Vá para o diretório do bot em um terminal e execute o seguinte comando para executar o bot localmente:
dotnet run
Abra seu emulador. Selecione Abrir Bot. Preencha a URL do Bot com
http://localhost:3978/api/messages
e os valores MicrosoftAppId e MicrosoftAppPassword. Se você tiver um bot JavaScript, poderá encontrar esses valores no arquivo .env do seu 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 Ligar.Agora abra outra janela do emulador. Esta segunda janela do emulador funcionará como um depurador. Siga as instruções conforme descrito na etapa anterior. Marque Abrir no modo de depuração e selecione Conectar.
Neste ponto, você verá um comando com um identificador exclusivo (
/INSPECT attach <identifier>
) em seu emulador de depuração. Copie todo o comando com o identificador do emulador de depuração e cole-o na caixa de chat do primeiro emulador.Nota
Um identificador exclusivo é gerado sempre que o emulador é iniciado no modo de depuração depois que você adiciona o middleware de inspeção no código do bot.
Agora você pode enviar mensagens na caixa de chat do seu primeiro emulador e inspecionar as mensagens no emulador de depuração. Para inspecionar o estado das mensagens, selecione Estado do Bot no Emulador de depuração e desdobre os valores na janela JSON direita. Você verá o estado do seu bot no emulador de depuração:
Se quiser inspecionar o estado do bot configurado no Azure e conectado a canais (como o Teams), será necessário instalar e executar os Túneis de Desenvolvimento.
Neste ponto, você atualizou seu emulador para a versão mais recente e adicionou o middleware de inspeção no código do bot. A próxima etapa é executar devtunnel e configurar seu bot local. Antes de executar o devtunnel, você precisa executar seu bot localmente.
Para executar seu bot localmente:
Vá para a pasta do seu bot em um terminal e defina seu registro npm para usar as compilações mais recentes
Execute seu bot localmente. Você verá seu bot expor um número de porta como
3978
.Abra outro prompt de comando e vá para a pasta de projeto do bot. Execute o seguinte comando:
devtunnel host -a -p 3978
O DevTunnel agora está conectado ao seu bot em execução local. Copie a URL pública segura (HTTPS).
Agora que seu bot local está conectado ao devtunnel, você pode configurar seu recurso de bot no Azure para usar a URL devtunnel.
Vá para seu recurso de bot no Azure. No menu à esquerda, em Configurações, selecione Configuração.
Defina o ponto de extremidade de mensagens para o endereço URL devtunnel copiado. Se necessário, adicione /api/messages após o endereço IP. Por exemplo,
https://0qg12llz-3978.usw2.devtunnels.ms/api/messages
.Selecione Ativar ponto de extremidade de streaming.
Selecione Aplicar para guardar as alterações.
Gorjeta
Se Aplicar não estiver habilitado, você poderá desmarcar Ativar ponto de extremidade de streaming e selecionar Aplicar, depois marcar Habilitar ponto de extremidade de streaming e selecionar Aplicar novamente. Você precisa certificar-se de que Ativar ponto de extremidade de streaming está marcado e a configuração do ponto de extremidade é salva.
Vá para o grupo de recursos do seu bot.
Selecione Implantação e, em seguida, selecione o recurso de bot que foi implantado anteriormente com êxito. Selecione Modelo no menu esquerdo para obter o MicrosoftAppId e o MicrosoftAppPassword para o aplicativo Web associado ao seu bot.
Atualize o arquivo de configuração do bot (appsettings.json para C# ou .env para JavaScript) com o MicrosoftAppId e o MicrosoftAppPassword.
Inicie o emulador, selecione Abrir Bot e insira
http://localhost:3978/api/messages
o URL do Bot. Preencha a ID do Aplicativo Microsoft e a senha do Aplicativo Microsoft com o mesmo MicrosoftAppId e MicrosoftAppPassword que você adicionou ao arquivo de configuração do nosso bot. Em seguida, selecione Conectar.Seu bot em execução agora está conectado ao seu recurso de bot no Azure. Para testar seu bot no Azure no Bate-papo da Web, vá para os recursos do bot, selecione Testar no Bate-papo da Web e envie mensagens para seu bot.
No emulador, selecione Depurar e, em seguida, Iniciar Depuração.
Insira o URL do devtunnel (não se esqueça de adicionar /api/messages) para o URL do Bot (por exemplo,
https://4jj51x75-51865.usw2.devtunnels.ms/api/messages
).- Para a ID do Aplicativo Microsoft, insira a ID do aplicativo do bot.
- Para obter a senha do aplicativo Microsoft, insira o segredo do aplicativo do bot.
- Certifique-se de que Abrir no modo de depuração também está marcado.
- Selecione Ligar.
Com o modo de depuração ativado, o emulador gera um UUID. Um UUID é um ID exclusivo gerado sempre que você inicia o modo de depuração no seu emulador.
Copie e cole o UUID na caixa de chat Testar no Web Chat da caixa de chat do seu canal. Você verá a mensagem "Anexado à sessão, todo o tráfego está sendo replicado para inspeção" na caixa de chat.
Você pode começar a depurar seu bot enviando mensagens na caixa de chat do canal configurado. Seu emulador 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 direita.
- Saiba como depurar seu bot usando arquivos de transcrição.
- Saiba como Depurar uma habilidade ou consumidor de habilidades.