Depurar seu aplicativo Teams

O Microsoft 365 Agents Toolkit (anteriormente conhecido como Teams Toolkit) ajuda você a depurar e visualizar seu aplicativo Microsoft Teams. Depurar é o processo de verificar, detectar e corrigir problemas ou bugs para garantir que o programa seja executado com êxito no Teams.

Depurar seu aplicativo Teams para Visual Studio Code

O Agents Toolkit no Microsoft Visual Studio Code automatiza o processo de depuração. Você pode detectar erros e corrigi-los, bem como visualizar o aplicativo Teams. Você também pode personalizar as configurações de depuração para criar sua guia ou bot.

Durante o processo de depuração:

  • O Agents Toolkit inicia automaticamente os serviços de aplicativo, inicia os depuradores e carrega o aplicativo Teams.
  • O Agents Toolkit verifica os pré-requisitos durante o processo de depuração em segundo plano.
  • Seu aplicativo do Teams está disponível para visualização no cliente Web do Teams localmente após a depuração.
  • Você também pode personalizar as configurações de depuração para usar seus pontos de extremidade de bot, certificado de desenvolvimento ou componente parcial de depuração para carregar seu aplicativo configurado.
  • O Visual Studio Code permite depurar a guia, o bot, a extensão de mensagem e o Azure Functions.

Principais recursos de depuração do Kit de Ferramentas de Agentes

O Agents Toolkit oferece suporte aos seguintes recursos de depuração:

O Agents Toolkit executa funções em segundo plano durante o processo de depuração, que incluem a verificação dos pré-requisitos necessários para a depuração. Você pode ver o progresso do processo de verificação no canal de saída do Kit de ferramentas de agentes. No processo de instalação, você pode registrar e configurar seu aplicativo do Teams.

Iniciar a depuração

Você pode pressionar F5 como uma única operação para iniciar a depuração. O Agents Toolkit começa a marcar os pré-requisitos, registra o aplicativo Microsoft Entra, o aplicativo Teams e registra o bot, inicia os serviços e inicia o navegador.

Depuração de vários destinos

O Agents Toolkit utiliza o recurso de depuração de vários destinos para depurar a guia, o bot, a extensão de mensagem e o Azure Functions ao mesmo tempo.

Alternar pontos de interrupção

Você pode alternar pontos de interrupção nos códigos-fonte das guias, bots, extensões de mensagens e do Azure Functions. Os pontos de interrupção são executados quando você interage com o aplicativo Teams em um navegador da Web. A imagem a seguir mostra o ponto de interrupção de alternância:

A captura de tela mostra os pontos de alternância de alternância.

Recarga dinâmica

Você pode atualizar e salvar os códigos-fonte da guia, do bot, da extensão de mensagem e do Azure Functions ao mesmo tempo ao depurar o aplicativo do Teams. O aplicativo é recarregado e o depurador é reconectado às linguagens de programação.

A captura de tela mostra o hot reload para códigos-fonte.

Parar a depuração

Ao concluir a depuração local, você pode selecionar Parar (Shift+F5) ou [Alt] Desconectar (Shift+F5) na barra de ferramentas de depuração flutuante para interromper todas as sessões de depuração e encerrar tarefas. A imagem a seguir mostra a ação parar a depuração:

A captura de tela mostra a opção parar depuração.

Playground de agentes do Microsoft 365

O Agents Playground facilita a depuração de seus aplicativos baseados em bot. Você pode conversar com seu bot e ver suas mensagens e Cartões Adaptáveis conforme eles aparecem no Teams. Você não precisa de uma conta de desenvolvedor do Microsoft 365, túnel ou registro de aplicativo e bot do Teams para usar o Agents Playground. Para obter mais informações, consulte Agents Playground.

Depurar aplicativos no cliente da área de trabalho do Teams

O Agents Toolkit ajuda você a depurar e visualizar seu aplicativo Microsoft Teams no cliente de desktop. Para obter mais informações, consulte depurar aplicativos no cliente de área de trabalho do Teams.

Preparar para depuração

As etapas a seguir ajudam você a se preparar para a depuração:

Entrar no Microsoft 365

Se você já se inscreveu no Microsoft 365, entre no Microsoft 365. Para obter mais informações, consulte Programa de desenvolvedor do Microsoft 365.

Alternar pontos de interrupção

Verifique se você pode alternar pontos de interrupção nos códigos-fonte de guias, bots, extensões de mensagem e Azure Functions. Para obter mais informações, consulte Alternar pontos de interrupção.

Personalizar configurações de depuração

O Agents Toolkit permite que você personalize as configurações de depuração para criar sua guia ou bot. Para obter mais informações sobre a lista completa de opções personalizáveis, consulte o documento de configurações de depuração.

Você também pode personalizar as configurações de depuração para seu aplicativo de bot existente.

Saiba como usar um bot existente para depuração

O Kit de Ferramentas de Agentes cria aplicativos do Microsoft Entra para projetos com bot por padrão usando a botAadApp/create ação.

Para usar um bot existente, você pode definir BOT_ID e SECRET_BOT_PASSWORD com env/.env.local seus próprios valores.

Use o seguinte exemplo de trecho de código para configurar um bot existente para depuração:

# env/.env.local

# Built-in environment variables
TEAMSFX_ENV=local

# Generated during provision, you can also add your own variables.
BOT_ID={YOUR_OWN_BOT_ID}
...

SECRET_BOT_PASSWORD={YOUR_OWN_BOT_PASSWORD}
...

Personalizar cenários

Aqui está uma lista de cenários de depuração que você pode usar:

Ignorar verificações de pré-requisitos

> "prerequisites" "Validate prerequisites" "args" >Em .vscode/tasks.json , atualize as verificações de pré-requisitos que você deseja ignorar.

A captura de tela mostra as verificações de pré-requisito de ignorar.

Use seu certificado de desenvolvimento

  1. Em m365agents.local.yml, remova devCert da devTool/install ação (ou remova a ação inteira devTool/install se ela contiver devCertapenas ).

  2. Em m365agents.local.yml, defina "SSL_CRT_FILE" e "SSL_KEY_FILE" em file/createOrUpdateEnvironmentFile ação para o caminho do arquivo de certificado e o caminho do arquivo de chave.

    # m365agents.local.yml
...
  # Remove devCert or this whole action
  - uses: devTool/install
    with:
      # devCert:
  ...
  - uses: file/createOrUpdateEnvironmentFile
    with:
      target: ./.localSettings
      envs:
        ...
        # set your own cert values
        SSL_CRT_FILE: ...
        SSL_KEY_FILE: ...
...
Personalizar comando de instalação do npm

Em m365agents.local.yml, edição args de cli/runNpmCommand ação.

# m365agents.local.yml
...
  - uses: cli/runNpmCommand
    with:
      # edit the npm command args
      args: install --no-audit
...
Modificar portas

  • Bot

    1. Pesquise "3978" em seu projeto e procure aparências em tasks.json e index.js.

    2. Substitua-a pela porta.

      A captura de tela mostra o resultado da pesquisa para substituir a porta para o bot.

  • Tab

    1. Pesquise "53000" em seu projeto e procure aparências em m365agents.local.yml e tasks.json.

    2. Substitua-a pela porta.

      A captura de tela mostra o resultado da pesquisa para substituir a porta para guia.

Usar seu próprio pacote de aplicativo

O Kit de Ferramentas de Agentes, por padrão, cria um conjunto de ações para gerenciar o pacote do teamsApp aplicativo. Você pode atualizá-los m365agents.local.yml para usar seu próprio pacote do aplicativo.

# m365agents.local.yml
...
  - uses: teamsApp/create # Creates a Teams app
    ...
  - uses: teamsApp/validateManifest # Validate using manifest schema
    ...
  - uses: teamsApp/zipAppPackage # Build Teams app package with latest env value
    ...
  - uses: teamsApp/validateAppPackage # Validate app package using validation rules
    ...
  - uses: teamsApp/update # Apply the app manifest (previously called Teams app manifest) to an existing Teams app in Teams Developer Portal.
    ...
...
Use seu próprio túnel

"Start Teams App Locally"Em .vscode/tasks.json , você pode atualizar "Start Local tunnel".

A captura de tela mostra as tarefas de usar seu próprio túnel. 

# env/.env.local

# Built-in environment variables
TEAMSFX_ENV=local
...
BOT_DOMAIN={YOUR_OWN_TUNNEL_DOMAIN}
BOT_ENDPOINT={YOUR_OWN_TUNNEL_URL}
...

# env/.env.local

# Built-in environment variables
TEAMSFX_ENV=local
...
BOT_DOMAIN={YOUR_OWN_TUNNEL_DOMAIN}
BOT_ENDPOINT={YOUR_OWN_TUNNEL_URL}
...
Adicionar variáveis de ambiente

Você pode adicionar variáveis de ambiente ao arquivo .localConfigs para guias, bots, extensão de mensagem e para o Azure Functions. O Agents Toolkit carrega as variáveis de ambiente adicionadas para iniciar os serviços durante a depuração local.

Observação

Certifique-se de iniciar uma nova depuração local depois de adicionar novas variáveis de ambiente, pois as variáveis de ambiente não dão suporte a recarga dinâmica.

Depurar componente parcial

O Agents Toolkit utiliza a depuração de vários destinos do Visual Studio Code para depurar guias, bots, extensões de mensagens e o Azure Functions ao mesmo tempo. Você pode atualizar .vscode/launch.json e .vscode/tasks.json para depurar componente parcial. Se você quiser depurar a guia somente em uma guia mais bot com o projeto do Azure Functions, use as seguintes etapas:

  1. Atualizar "Attach to Bot" e "Attach to Backend" do composto de depuração em .vscode/launch.json.

    {
    "name": "Debug in Teams (Edge)",
     "configurations": [
        "Attach to Frontend (Edge)",
        // "Attach to Bot",
        // "Attach to Backend"
        ],
        "preLaunchTask": "Start Teams App Locally",
        "presentation": {
            "group": "all",
            "order": 1
        },
        "stopAll": true

}

  2. Atualizar "Start Backend" e "Start Bot" da tarefa Iniciar Tudo em .vscode/tasks.json.

    {

    "label": "Start application",
    "dependsOn": [
        "Start Frontend",
          // "Start Backend",
          // "Start Bot"

      ]

}
Atualize a ID de segredo do cliente expirada para os aplicativos existentes

  1. Acesse o portal do Azure.

  2. Selecione Registros de aplicativos.

    A captura de tela mostra os serviços do Azure para selecionar Registros de aplicativo.

  3. Selecione + Novo registro.

    A captura de tela mostra a página Novo registro no centro de administração do Microsoft Entra.

  4. Insira o nome do seu aplicativo.

  5. Selecione Contas em qualquer diretório organizacional (Qualquer locatário do Microsoft Entra ID - Multilocatário).

  6. Selecione Registrar.

    A captura de tela mostra a opção de registrar o bot no centro de administração do Microsoft Entra.

    Seu aplicativo está registrado no Microsoft Entra ID. A página de visão geral do aplicativo é exibida.

    A captura de tela mostra a página de visão geral do registro do aplicativo.

  7. No painel esquerdo, selecione Certificados e segredos para criar um segredo do cliente para seu aplicativo.

    1. Em Segredos do cliente, selecione ➕ Novo segredo do cliente.
    2. Adicione uma descrição para identificar esse segredo e diferenciá-lo de outros que você talvez precise criar para esse aplicativo, como, por exemplo, Identidade do aplicativo de bot no Teams.
    3. Configure Expira em para a sua seleção.
    4. Selecione Adicionar.

  8. Atualize o .env arquivo com o segredo do bot.

  9. Provisione ou implante o aplicativo conforme necessário.

  10. Se o aplicativo já estiver implantado, certifique-se de atualizar a configuração do serviço de aplicativo no recurso do Azure com o segredo de bot recém-criado.

Avançar

Depurar seu aplicativo localmente

Confira também

  • Last updated on