Partilhar via

Diretrizes de depuração

  • Artigo

APLICA-SE A: SDK v4

Os bots são aplicativos complexos, com muitas partes trabalhando juntas. Como qualquer outro aplicativo complexo, isso pode levar a alguns bugs interessantes ou fazer com que seu bot se comporte de forma diferente do esperado.

Depurar, seu bot às vezes pode ser uma tarefa difícil. Cada desenvolvedor tem sua própria maneira preferida de realizar essa tarefa. As diretrizes abaixo são sugestões que se aplicam à maioria dos bots.

Depois de verificar se o bot funciona, a próxima etapa é conectá-lo a um canal. Para fazer isso, você pode implantar seu bot em um servidor de preparo e criar seu próprio cliente de linha direta para o bot se conectar. Para obter mais informações, consulte Conectar um bot a uma linha direta.

Criar seu próprio cliente permite que você defina o funcionamento interno do canal e teste como seu bot responde a determinadas trocas de atividades. Uma vez conectado ao seu cliente, execute seus testes para configurar o estado do bot e verificar seus recursos. Se o bot utilizar um recurso como fala, o uso desses canais pode oferecer uma maneira de verificar essa funcionalidade.

Nota

Ao implantar um bot no Azure, o canal de Chat da Web é provisionado por padrão.

O uso do Emulador do Bot Framework e do Bate-papo da Web por meio do portal do Azure aqui pode fornecer mais informações sobre o desempenho do bot ao interagir com diferentes canais.

A depuração do bot funciona de forma semelhante a outros aplicativos multi-threaded, com a capacidade de definir pontos de interrupção ou usar recursos como a janela imediata.

Os bots seguem um paradigma de programação orientada a eventos, que pode ser difícil de racionalizar se você não estiver familiarizado com ele. A ideia de seu bot ser stateless, multi-threaded e lidar com chamadas async/await pode resultar em bugs inesperados. Embora a depuração do seu bot funcione de forma semelhante a outros aplicativos multi-threaded, abordaremos algumas sugestões, ferramentas e recursos para ajudar.

Noções básicas sobre atividades de bot com o emulador

Seu bot lida com diferentes tipos de atividades além da atividade normal de mensagens. Entender essas atividades ajudará você a codificar seu bot de forma eficiente e permitirá que você verifique se as atividades que seu bot está enviando e recebendo são o que você espera. Usando o emulador irá mostrar-lhe quais são essas atividades, quando elas acontecem e quais informações elas contêm. Para obter mais informações, consulte Depurar com o emulador.

Salvando e recuperando interações do usuário com transcrições

O armazenamento de transcrições de blob do Azure fornece um recurso especializado onde você pode armazenar e recuperar transcrições contendo interações entre seus usuários e seu bot.

Além disso, depois que as interações de entrada do usuário tiverem sido armazenadas, você poderá usar o "gerenciador de armazenamento" do Azure para exibir manualmente os dados contidos nas transcrições armazenadas em seu repositório de transcrições de blob. O exemplo a seguir abre "storage explorer" nas configurações de "mynewtestblobstorage". Para abrir uma entrada de usuário salva, selecione: Blob Container > ChannelId > TranscriptId > ConversationId

Exemplo de uma entrada de transcrição armazenada em um repositório de transcrição de blob.

Isso abre a entrada de conversa do usuário armazenada no formato JSON. A entrada do usuário é preservada juntamente com a chave "text:". Para obter mais informações sobre como criar e usar um arquivo de transcrição de bot, consulte Depurar seu bot usando arquivos de transcrição.

Como funciona o middleware

O middleware pode não ser intuitivo ao tentar usá-lo pela primeira vez, particularmente no que diz respeito à continuação, ou curto-circuito, da execução. O middleware pode ser executado na borda principal ou final de uma volta, com uma chamada para o delegado ditando quando a next() execução é passada para a lógica do bot.

Se você estiver usando várias peças de middleware e é como seu pipeline é orientado, o delegado pode passar a execução para uma parte diferente de middleware. Os detalhes sobre o pipeline de middleware do bot podem ajudar a tornar essa ideia mais clara.

Se o next() delegado não for chamado, isso é chamado de roteamento de curto-circuito. Isso acontece quando o middleware satisfaz a atividade atual e determina que não é necessário passar a execução adiante.

Entender quando e por que os curto-circuitos de middleware podem ajudar a indicar qual parte do middleware deve vir primeiro em seu pipeline. Além disso, entender o que esperar é importante para o middleware interno fornecido pelo SDK ou outros desenvolvedores. Alguns acham útil tentar criar seu próprio middleware primeiro para experimentar um pouco antes de mergulhar no middleware integrado.

Para obter mais informações sobre como depurar um bot usando middleware de inspeção, consulte Depurar um bot com middleware de inspeção.

Compreender o estado

Acompanhar o estado é uma parte importante do seu bot, especialmente para tarefas complexas. Em geral, a prática recomendada é processar as atividades o mais rápido possível e deixar o processamento concluído para que o estado seja persistente. As atividades podem ser enviadas para seu bot quase ao mesmo tempo, e isso pode introduzir bugs confusos por causa da arquitetura assíncrona.

Mais importante ainda, certifique-se de que esse estado persiste de uma forma que corresponda às suas expectativas. Dependendo de onde seu estado persistente vive, os emuladores de armazenamento para o Cosmos DB e o armazenamento de Tabela do Azure podem ajudá-lo a verificar esse estado antes de usar o armazenamento de produção.

Importante

A classe de armazenamento do Cosmos DB foi preterida. Os contêineres originalmente criados com CosmosDbStorage não tinham nenhuma chave de partição definida e receberam a chave de partição padrão de _/partitionKey.

Os contêineres criados com o armazenamento do Cosmos DB podem ser usados com o armazenamento particionado do Cosmos DB. Leia Particionamento no Azure Cosmos DB para obter mais informações.

Observe também que, ao contrário do armazenamento herdado do Cosmos DB, o armazenamento particionado do Cosmos DB não cria automaticamente um banco de dados em sua conta do Cosmos DB. Você precisa criar um novo banco de dados manualmente, mas ignore a criação manual de um contêiner, pois CosmosDbPartitionedStorage criará o contêiner para você.

Como usar manipuladores de atividade

Os manipuladores de atividades podem introduzir outra camada de complexidade, especialmente porque cada atividade é executada em um thread independente (ou web workers, dependendo do seu idioma). Dependendo do que seus manipuladores estão fazendo, isso pode causar problemas em que o estado atual não é o esperado.

O estado interno é gravado no final de um turno, no entanto, todas as atividades geradas por esse turno são executadas independentemente do pipeline de turno. Muitas vezes, isso não nos afeta, mas se um manipulador de atividades muda de estado, precisamos do estado escrito para conter essa alteração. Nesse caso, o pipeline de turno pode esperar que a atividade termine o processamento antes de concluir para garantir que ele registre o estado correto para esse turno.

O método de atividade de envio e seus manipuladores representam um problema exclusivo. Simplesmente chamar a atividade send de dentro do manipulador de atividades on send causa uma bifurcação infinita de threads. Há maneiras de contornar esse problema, como anexando mensagens adicionais às informações de saída ou gravando em outro local, como o console ou um arquivo, para evitar travar seu bot.

Depurando um bot de produção

Quando seu bot está em produção, você pode depurá-lo de qualquer canal usando Dev Tunnels. A conexão perfeita do seu bot a vários canais é um recurso fundamental disponível no Bot Framework. Para obter mais informações, consulte Depurar um bot de qualquer canal usando devtunnel e Depurar um consumidor de habilidade ou habilidade.

Próximos passos

Como testar bots de unidade

Recursos adicionais