Testar e depurar com o Emulator
APLICA-SE A: SDK v4
O Bot Framework Emulator é um aplicativo da área de trabalho que permite que os desenvolvedores de bot testem e depurem seus bots, seja local ou remotamente. Usando o Emulator, você pode conversar com seu bot e inspecionar as mensagens enviadas e recebidas por ele. O Emulator exibe as mensagens como elas serão mostradas em uma interface do usuário do Webchat e registra as solicitações e as respostas JSON à medida que você troca mensagens com o bot. Antes de implantar seu bot na nuvem, execute-o localmente e teste-o usando o Emulator. Teste seu bot usando o Emulator mesmo que você ainda não o tenha criado com o Serviço de Bot de IA do Azure nem o tenha configurado para execução em nenhum canal.
Observação
Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.
Os bots existentes criados com o SDK para Java 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 copiloto certa.
Para obter mais informações, confira O futuro da criação de bots.
Pré-requisitos
- Instalar o Bot Framework Emulator
Executar um bot localmente
Antes de conectar o bot ao Bot Framework Emulator, você precisa executar o bot localmente. Você pode usar o Visual Studio, o Visual Studio Code ou a linha de comando para executar o bot. Para executar um bot usando a linha de comando, faça o seguinte:
Acesse o prompt de comando e altere o diretório para o diretório de projeto do bot.
Inicie o bot executando o seguinte comando:
dotnet runCopie o número da porta na linha antes do início do aplicativo. Pressione CTRL+C para desligar.
Neste ponto, seu bot está em execução localmente.
Conectar-se a um bot em execução no localhost
Definir configurações de proxy
Quando estiver desenvolvendo atrás de um proxy corporativo, o Emulator usará as variáveis de ambiente configuradas HTTP_PROXY e HTTPS_PROXY, que especificam o roteiro de URL do proxy para solicitações HTTP e HTTPs, respectivamente.
Se estiver se conectando a um bot em execução no localhost, o Emulator primeiro tentará encaminhar pelo proxy antes de se conectar ao localhost. Normalmente, o proxy bloqueará a conexão, a menos que você especifique que ela deve ser ignorada para localhost.
Para ignorar as configurações HTTP_PROXY e HTTPS_PROXY e permitir que o Emulator se conecte ao localhost, em seu computador local, você deve definir a seguinte variável de ambiente:
NO_PROXY=localhost
Configurar o Emulator para autenticação
Se um bot exigir autenticação, exibindo uma caixa de diálogo de logon, você deverá configurar o Emulator, conforme mostrado abaixo.
Como usar o código de verificação de credenciais
- Inicie o Emulator.
- No Emulator, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
- Habilite Usar um código de verificação de credenciais para OAuthCards.
- Selecione Salvar.
Ao selecionar o botão de logon exibido pelo bot, um código de validação será gerado. Insira o código na caixa de conversa de entrada do bot para que a autenticação ocorra. Depois disso, será possível executar as operações permitidas.
Como alternativa é possível executar as etapas descritas abaixo.
Como usar os tokens de autenticação
- Inicie o Emulator.
- No Emulator, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
- Habilite Usar tokens de autenticação da versão 1.0.
- Selecione Salvar.
Ao selecionar o botão de logon exibido pelo bot, você será solicitado a inserir suas credenciais. Um token de autenticação será gerado. Depois disso, será possível executar as operações permitidas.
Para se conectar a um bot em execução localmente, selecione Abrir bot. Adicione o número da porta que você copiou anteriormente na URL a seguir e cole a URL atualizada na barra URL do Bot:
http://localhost:<port number>/api/messages
Se o bot é executado com credenciais da MSA (Conta Microsoft), insira-as também.
Usar credenciais do bot
Quando você abre o bot, defina a ID do aplicativo Microsoft e a senha do aplicativo Microsoft se seu bot está em execução com as credenciais. Se você criou seu bot com o Serviço de Bot de IA do Azure, as credenciais estão disponíveis no Serviço de Aplicativo do bot, na seção Configurações -> Configuração. Se não souber os valores, você poderá remover aqueles do arquivo de configuração do bot sendo executado localmente e depois executar o bot no Emulator. Se o bot não estiver em execução com essas configurações, você também não precisará executar o Emulator com as configurações.
Ao criar um aplicativo de provedor de identidade do AD, lembre-se do seguinte:
- Quando o tipo de conta compatível for definido como locatário único, se você usar uma assinatura pessoal em vez de uma conta Microsoft, o Emulator emitirá o erro: a ID do Aplicativo da Microsoft ou a senha do aplicativo da Microsoft do bot está incorreta.
- Nesse caso, os tipos de conta compatíveis devem ser definidos como Contas em qualquer diretório organizacional (Qualquer diretório do Microsoft Entra ID – Multilocatário) e contas Microsoft pessoais (por exemplo, Xbox).
Para obter mais informações, confira Criar um aplicativo de provedor de identidade no Microsoft Entra ID e Registrar um novo aplicativo usando o portal do Azure.
Exibir as atividades de mensagem detalhadas com o Inspetor de
Envie uma mensagem ao bot, que deve responder de volta. Você pode selecionar a bolha de mensagem dentro da janela de conversa e inspecionar a atividade JSON bruta usando o recurso INSPETOR à direita da janela. Quando selecionada, o balão de mensagens ficará amarelo e o objeto JSON de atividade será exibido à esquerda da janela de bate-papo. As informações de JSON incluem metadados principais, incluindo ID do canal, tipo de atividade, ID da conversa, mensagem de texto, URL de ponto de extremidade, etc. Você pode inspecionar as atividades de inspeção enviadas pelo usuário e as atividades com as quais o bot responde.
Dica
Você pode depurar alterações de estado em um bot conectado a um canal adicionando middleware de inspeção ao bot.
Inspecionar serviços
Observação
O QnA Maker da IA do Azure será desativada em 31 de março de 2025. A partir de 1° de outubro de 2022, não será mais possível criar recursos ou bases de conhecimento do QnA Maker. Uma versão mais recente da funcionalidade de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure.
Respostas às perguntas personalizadas, um recurso de Linguagem de IA do Azure, é a versão atualizada do serviço QnA Maker. Para obter mais informações sobre o suporte a perguntas e respostas no SDK do Bot Framework, confira reconhecimento de linguagem natural.
Observação
O reconhecimento de linguagem (LUIS) será desativado em 1º de outubro de 2025. A partir de 1º de abril de 2023, você não poderá criar recursos do LUIS. Uma versão mais recente do reconhecimento de linguagem já está disponível como parte da Linguagem de IA do Azure.
A compreensão da linguagem coloquial (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte ao reconhecimento de linguagem no SDK do Bot Framework, confira Reconhecimento de linguagem natural.
Com o novo Emulator, você também pode inspecionar as respostas JSON de LUIS e QnA Maker. Usando um bot com um serviço de idiomas conectado, você pode selecionar trace na janela LOG no canto inferior direito. Esta nova ferramenta também fornece recursos para atualizar seus serviços de linguagem diretamente do Emulator.
Com um serviço LUIS conectado, você notará que o link de rastreamento especifica o rastreamento do LUIS. Quando selecionado, você verá a resposta bruta de seu serviço LUIS, que inclui intenções, entidades juntamente com suas pontuações especificadas. Você pode ceder intenções para seus enunciados de usuário.
Com um serviço QnA Maker conectado, o log exibirá o rastreamento do QnA. Quando selecionado, será exibida a preview do par de perguntas e respostas associado a essa atividade, juntamente com uma pontuação de confiança. A partir daqui, você pode adicionar frases de pergunta alternativo para uma resposta.
Entrar no Azure
Você pode usar o Emulator para iniciar sessão em sua conta do Azure. Isso é particularmente útil para adicionar e gerenciar os serviços que dependem do seu bot. Para iniciar sessão:
Selecione Arquivo e Iniciar sessão no Azure.
Na tela de boas-vindas, selecione Iniciar sessão com sua conta do Azure. Opcionalmente, o Emulator pode manter você conectado entre as reinicializações dele.
Desabilitar a coleção de dados
Se decidir que não deseja permitir que o Emulator colete dados de uso, você pode facilmente desabilitar a coleção de dados, seguindo estas etapas:
No Emulator, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
Na seção Coleção de dados, desmarque a caixa de seleção Ajude-nos a melhorar o Emulator permitindo-nos coletar dados de uso.
Selecione Salvar.
Se você mudar de ideia, poderá reativar a coleção de dados mais tarde.
Recursos adicionais
O Bot Framework Emulator é open source. Você pode contribuir com o desenvolvimento e enviar bugs e sugestões.
Para solucionar problemas, confira solucionar problemas gerais e outros artigos de solução de problemas nesta seção.
Próxima etapa
Use o middleware de inspeção para depurar um bot conectado a um canal.