Share via

Depurar suplementos do Office no Windows usando Visual Studio Code e Microsoft Edge WebView2 (baseado em Chromium)

  • Artigo

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

Importante

Este artigo só se aplica quando o Office executa suplementos no runtime do Microsoft Edge Chromium WebView2, conforme explicado em Navegadores e controles webview usados pelos Suplementos do Office. Para obter instruções sobre a depuração em Visual Studio Code em Versão Prévia do Microsoft Edge com o runtime original do WebView (EdgeHTML), consulte Extensão de Depurador de Suplemento do Office para Visual Studio Code.

Dica

Se você não puder ou não desejar depurar usando ferramentas internas em Visual Studio Code; ou estiver encontrando um problema que só ocorre quando o suplemento é executado fora do Visual Studio Code, você pode depurar o runtime do Edge Chromium WebView2 usando as ferramentas de desenvolvedor do Edge (baseada em Chromium), 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>Execução ou insira Ctrl+Shift+D para alternar para a exibição de depuração.

  4. Nas opções EXECUTAR E DEPURAR, escolha a opção Chromium de Borda para seu aplicativo host, como Outlook Desktop (Edge Chromium). Selecione F5 ou escolha Executar>Iniciar Depuração no menu para começar 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 B 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 parar 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 Node e tentar fechar o aplicativo host, mas haverá um prompt no aplicativo host perguntando se você deve 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---stop de 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 não criado com o Yo Office

Se o projeto não foi criado com o Yo Office, você precisará criar uma configuração de depuração para 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 projeto e responda aos prompts.

  2. Execute npm install office-addin-debugging. Esse pacote carrega seu suplemento para depuração.

  3. Abra o arquivo package.json. scripts Na 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 o local da pasta do manifesto.

  5. Substitua $SERVER_START$ pelo comando para iniciar seu 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 JSON a seguir no 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 JSON a seguir no arquivo. Ele contém uma tarefa que inicia a depuração para seu 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 tarefa única à 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 B

  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