Depurar Suplementos do Office no Windows usando o Visual Studio Code e o Microsoft Edge WebView2

Os suplementos do Office em execução no Windows podem depurar no tempo de execução do Edge diretamente no Visual Studio Code.

Dica

Se você não puder ou não quiser depurar usando ferramentas internas no Visual Studio Code; ou estiver encontrando um problema que ocorre apenas quando o suplemento é executado fora do Visual Studio Code, você pode depurar o tempo de execução do Microsoft Edge WebView2 usando as ferramentas de desenvolvedor do Edge, conforme descrito em Depurar suplementos usando ferramentas de desenvolvedor para o Microsoft Edge WebView2.

Esse modo de depuração é dinâmico, permitindo definir pontos de interrupção enquanto o código está em execução. Consulte as alterações em seu código imediatamente enquanto o depurador está anexado, tudo sem perder sua sessão de depuração. As alterações de código também persistem, para que você veja os resultados de várias alterações em seu código. A imagem a seguir mostra essa extensão em ação.

Extensão do Depurador de Suplemento do Office depurando uma seção de suplementos do Excel.

Pré-requisitos

Depurar um projeto criado com o Yo Office

Estas instruções assumem que você tem experiência com o uso da linha de comando, que entende JavaScript básico e criou um projeto de Suplemento do Office antes de usar o gerador Yeoman para Suplementos do Office. Se você não tiver feito isso antes, veja um de nossos tutoriais, tal como o tutorial do Suplemento do Office Excel.

  1. A primeira etapa depende do projeto e de como ele foi criado.

  2. Abra VS Code e abra seu projeto nele.

  3. Escolha Exibir>Executar ou insira Ctrl+Shift+D para alternar para o modo de exibição de depuração.

  4. Nas opções EXECUTAR E DEPURAR, escolha a opção Microsoft Edge para seu aplicativo host, como a Área de Trabalho do Outlook (Edge Chromium). Selecione F5 ou escolha Executar>Iniciar Depuração no menu para iniciar a depuração. Esta ação inicia automaticamente um servidor local em uma janela de Nó para hospedar seu suplemento e depois abre automaticamente o aplicativo host, como o Excel ou Word. Isso pode levar vários segundos.

    Dica

    Se você não estiver usando um projeto criado com o Yo Office, talvez seja solicitado a ajustar uma chave do registro. Enquanto estiver na pasta raiz do seu projeto, execute o seguinte na linha de comando.

    npx office-addin-debugging start <your manifest path>

    Importante

    Se o seu projeto foi criado com versões mais antigas do Yo Office, você poderá ver a caixa de diálogo de erro a seguir cerca de 10 a 30 segundos depois de começar a depuração (nesse ponto você pode já ter passado para outra etapa neste procedimento) e ela pode estar oculta atrás da caixa de diálogo descrita na próxima etapa.

    O erro diz que a borda do tipo de depuração configurada não tem suporte.

    Conclua as tarefas no Apêndice e reinicie este procedimento.

  5. No aplicativo host, seu suplemento agora está pronto para uso. Selecione Mostrar Painel de Tarefas ou execute qualquer outro comando de suplemento. Uma caixa de diálogo aparecerá com texto semelhante ao seguinte:

    WebView Stop On Load. Para depurar o modo de exibição da Web, anexe o VS Code à instância de modo de exibição da Web usando o Depurador da Microsoft para extensão do Edge, e clique em OK para continuar. Para impedir que essa caixa de diálogo seja exibida no futuro, clique em Cancelar.

    Selecione OK.

    Observação

    Se você selecionar Cancelar, a caixa de diálogo não será mostrada novamente enquanto esta instância do suplemento estiver em execução. No entanto, se você reiniciar o suplemento, você verá a caixa de diálogo novamente.

  6. Agora você pode definir pontos de interrupção no código e depuração do projeto. Para definir pontos de interrupção Visual Studio Code, passe o mouse ao lado de uma linha de código e selecione o círculo vermelho que aparece.

    O círculo vermelho aparece em uma linha de código no Visual Studio Code.

  7. Execute a funcionalidade no seu complemento que chama as linhas com pontos de interrupção. Você verá que os pontos de interrupção foram atingidos e você pode inspecionar variáveis locais.

    Observação

    Pontos de interrupção em chamadas de Office.initialize ou Office.onReady são ignorados. Para obter detalhes sobre essas funções, consulte Inicializar seu Suplemento do Office.

Importante

A melhor maneira de interromper uma sessão de depuração é selecionar Shift+F5 ou escolher Executar>Parar Depuração no menu. Essa ação deve fechar a janela do servidor de nó e tentar fechar o aplicativo host, mas haverá um prompt no aplicativo host perguntando se você deseja salvar o documento ou não. Faça uma escolha apropriada e deixe o aplicativo host fechar. Evite fechar manualmente a janela de Nó ou o aplicativo host. Fazer isso pode causar bugs, especialmente quando você interrompe e inicia sessões de depuração repetidamente.

Se a depuração parar de funcionar---por exemplo, se os pontos de interrupção estiverem sendo ignorados---pare a depuração. Em seguida, se necessário, feche todas as janelas do aplicativo host e a janela de Nó. Finalmente, feche o Visual Studio Code e abra-o novamente.

Depurar um projeto que não foi criado com o Yo Office

Se seu projeto não foi criado com o Yo Office, você precisará criar uma configuração de depuração para o Visual Studio Code.

Configurar package.json arquivo

  1. Verifique se você tem um package.json arquivo. Se você ainda não tiver um arquivo package.json, execute npm init na pasta raiz do seu projeto e responda às solicitações.

  2. Execute npm install office-addin-debugging. Este pacote faz sideload em seu suplemento para depuração.

  3. Abra o arquivo package.json. Na scripts seção, adicione o script a seguir.

    "start:desktop": "office-addin-debugging start $MANIFEST_FILE$ desktop",
"dev-server": "$SERVER_START$"

  4. Substitua $MANIFEST_FILE$ pelo nome do arquivo correto e pelo local da pasta do manifesto.

  5. Substitua $SERVER_START$ pelo comando para iniciar o servidor Web. Posteriormente nestas etapas, o office-addin-debugging pacote procurará especificamente o dev-server script para iniciar seu servidor Web.

  6. Salve e feche o package.json arquivo.

Configurar launch.json arquivo

  1. Crie um arquivo nomeado launch.json na \.vscode pasta do projeto se ainda não houver um.

  2. Copie o seguinte JSON para o arquivo.

    {
  // Other properties may be here.
  "configurations": [
    {
      "name": "$HOST$ Desktop (Edge Chromium)",
      "type": "msedge",
      "request": "attach",
      "useWebView": true,
      "port": 9229,
      "timeout": 600000,
      "webRoot": "${workspaceRoot}",
      "preLaunchTask": "Debug: Excel Desktop"
    }
  ]
  // Other properties may be here.
}

    Observação

    Se você já tiver um launch.json arquivo, basta adicionar a configuração única à configurations seção.

  3. Substitua o espaço reservado $HOST$ pelo nome do aplicativo do Office no qual o suplemento é executado. Por exemplo: Outlook ou Word.

  4. Salve e feche o arquivo.

Configurar tasks.json

  1. Crie um arquivo nomeado tasks.json na \.vscode pasta do projeto.

  2. Copie o seguinte JSON para o arquivo. Ele contém uma tarefa que inicia a depuração do suplemento.

    {
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Debug: $HOST$ Desktop",
      "type": "shell",
      "command": "npm",
      "args": ["run", "start:desktop", "--", "--app", "$HOST$"],
      "presentation": {
        "clear": true,
        "panel": "dedicated"
      },
      "problemMatcher": []
    }
  ]
}

    Observação

    Se você já tiver um tasks.json arquivo, basta adicionar a única tarefa à tasks seção.

  3. Substitua ambas as instâncias do espaço reservado $HOST$ pelo nome do aplicativo do Office no qual o suplemento é executado. Por exemplo: Outlook ou Word.

Agora você pode depurar seu projeto usando o depurador do VS Code (F5).

Apêndice

  1. Na caixa de diálogo erro, selecione o botão Cancelar.
  2. Se a depuração não parar automaticamente, selecione Shift+F5 ou escolha Executar>Parar Depuração no menu.
  3. Feche a janela Nó onde o servidor local está sendo executado, se ele não fechar automaticamente.
  4. Feche o aplicativo do Office se ele não fechar automaticamente.
  5. Abra o \.vscode\launch.json arquivo no projeto.
  6. Na matriz configurations, há vários objetos de configuração. Localize aquele cujo nome tem o padrão $HOST$ Desktop (Edge Chromium), onde $HOST$ é um aplicativo do Office que seu suplemento executa; por exemplo, Outlook Desktop (Edge Chromium) ou Word Desktop (Edge Chromium).
  7. Altere o valor da propriedade "type" de "edge" para "pwa-msedge".
  8. Altere o valor da propriedade "useWebView" da cadeia de caracteres "advanced" para o booleano true (observe que não há aspas ao redor do true).
  9. Salve o arquivo.
  10. Feche VS Code.

Confira também

  • Last updated on