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.

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.

Pré-requisitos

• Código do Visual Studio
• Node.js (a versão LTS ativa mais recente)
• Windows 10, 11
• Uma combinação de plataforma e aplicativo do Office que dá suporte ao Microsoft Edge com o WebView2, conforme explicado em Navegadores e controles do modo de exibição da Web usados pelos Suplementos do Office. Se a sua versão do Office de uma assinatura do Microsoft 365 for anterior à versão 2101, você precisará instalar o WebView2. Para obter instruções para instalar o WebView2, consulte Microsoft Edge WebView2 / Incorporar conteúdo da web ... com o Microsoft Edge WebView2.

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.

   • Se você quiser criar um projeto para experimentar a depuração no Visual Studio Code, use o gerador Yeoman para Suplementos do Office. Siga qualquer um dos guias de início rápido do Yo Office, como o início rápido do suplemento do Outlook.
   • Se você quiser depurar um projeto existente que foi criado com Yo Office, pule para a próxima etapa.

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.

   

   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.

   

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.

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

• Testar e depurar Suplementos do Office
• Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge
• Anexar um depurador do painel de tarefas
• Runtimes em Suplementos do Office