Depurar suplementos usando ferramentas de desenvolvedor na Internet Explorer

Este artigo mostra como depurar o código do lado do cliente (JavaScript ou TypeScript) do suplemento quando as seguintes condições forem atendidas.

• Você não pode ou não deseja depurar usando ferramentas internas no IDE; ou você está encontrando um problema que só ocorre quando o suplemento é executado fora do IDE.
• Seu computador está usando uma combinação de versões do Windows e do Office que usam o controle webview da Internet Explorer, Trident.

Para determinar qual navegador ou visão da Web está sendo usado em seu computador, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office.

Dica

Em versões recentes do Office, uma maneira de identificar o controle webview que o Office está usando é por meio do menu de personalidade em qualquer suplemento em que ele está disponível. (O menu de personalidade não tem suporte no Outlook.) Abra o menu e selecione Informações de Segurança. Na caixa de diálogo Informações de Segurança no Windows, o Runtime relata microsoft Edge, Versão Prévia do Microsoft Edge ou Internet Explorer. O runtime não está incluído na caixa de diálogo em versões mais antigas do Office.

Observação

Para instalar uma versão do Office que usa o Trident ou para forçar sua versão atual a usar o Trident, consulte Alternar para a visão web do Trident.

Depurar um suplemento de painel de tarefas usando as ferramentas F12

Windows 10 e 11 incluem uma ferramenta de desenvolvimento web chamada "F12" porque ela foi originalmente lançada pressionando f12 na Internet Explorer. O F12 agora é um aplicativo independente usado para depurar seu suplemento quando ele está em execução no controle webview da Internet Explorer, Trident. O aplicativo não está disponível em versões anteriores do Windows.

Observação

Se o suplemento tiver um comando de suplemento que executa uma função, a função será executada em um processo de runtime oculto do navegador ao qual as ferramentas F12 não podem detectar ou anexar, portanto, a técnica descrita neste artigo não pode ser usada para depurar o código na função.

As etapas a seguir são as instruções para depurar seu suplemento. Se você quiser apenas testar as próprias ferramentas F12, consulte Exemplo de suplemento para testar as ferramentas F12.

1. Carregar lateralmente e executar o suplemento.

2. Inicie as ferramentas de desenvolvimento F12 que correspondem à sua versão do Office.

   • Para a versão de 32 bits do Office, use C:\Windows\System32\F12\F12Chooser.exe
   • Para a versão de 64 bits do Office, use C:\Windows\SysWOW64\F12\F12Chooser.exe

   O IEChooser é aberto com uma janela chamada Escolher destino para depuração. Seu suplemento será exibido na janela nomeada pelo nome do arquivo da home page do suplemento. Na captura de tela a seguir, é Home.html. Somente os processos que estão em execução no Explorer da Internet, ou Trident, são exibidos. A ferramenta não pode anexar a processos que estão em execução em outros navegadores ou visões da Web, incluindo o Microsoft Edge.

   

3. Selecione o processo do suplemento; ou seja, o nome do arquivo da página inicial. Essa ação anexará as ferramentas F12 ao processo e abrirá o main interface do usuário F12.

4. Abra a guia Depurador.

5. Na parte superior esquerda da guia, logo abaixo da faixa de opções de ferramenta de depurador, há um pequeno ícone de pasta. Selecione isso para abrir uma lista suspensa dos arquivos no suplemento. Apresentamos um exemplo a seguir.

   

6. Selecione o arquivo que você deseja depurar e ele será aberto no painel script (à esquerda) da guia Depurador . Se você estiver usando um transpiler, empacotador ou minifiador, que altera o nome do arquivo, ele terá o nome final que é realmente carregado, não o nome do arquivo de origem original.

7. Role até uma linha em que você deseja definir um ponto de interrupção e clique na margem à esquerda do número da linha. Você verá um ponto vermelho à esquerda da linha e uma linha correspondente será exibida na guia Pontos de interrupção do painel inferior direito. A captura de tela a seguir é um exemplo.

   

8. Execute funções no suplemento conforme necessário para disparar o ponto de interrupção. Quando o ponto de interrupção é atingido, uma seta de ponta direita é exibida no ponto vermelho do ponto de interrupção. A captura de tela a seguir é um exemplo.

   

Dica

Para obter mais informações sobre como usar as ferramentas F12, consulte Inspecionar o JavaScript em execução com o Depurador.

Suplemento de exemplo para testar as ferramentas F12

Este exemplo usa o Word e um suplemento gratuito do AppSource.

1. Abra o Word e escolha um documento em branco.
2. >SelecioneSuplementos Domésticos e, em seguida, selecione Obter Suplementos.
3. Na caixa de diálogo Suplementos do Office , selecione a guia STORE .
4. Selecione o suplemento QR4Office . Ele é aberto em um painel de tarefas.
5. Inicie as ferramentas de desenvolvimento F12 que correspondem à sua versão do Office, conforme descrito na seção anterior.
6. Na janela F12, selecione Home.html.
7. Na guia Depurador , abra o arquivoHome.js conforme descrito na seção anterior.
8. Defina os pontos de interrupção nas linhas 310 e 312.
9. No suplemento, selecione o botão Inserir . Um ou outro ponto de interrupção é atingido.

Depurar uma caixa de diálogo em um suplemento

Se o suplemento usar a API de Diálogo do Office, a caixa de diálogo será executada em um processo separado do painel de tarefas (se houver) e as ferramentas devem ser anexadas a esse processo. Siga estas etapas.

1. Execute o suplemento e as ferramentas.
2. Abra a caixa de diálogo e selecione o botão Atualizar nas ferramentas. O processo de caixa de diálogo é mostrado. Seu nome é o nome do arquivo que está aberto na caixa de diálogo.
3. Selecione o processo para abri-lo e depurar, conforme descrito na seção Depurar um suplemento do painel de tarefas usando as ferramentas F12.

Alternar para a webview do Trident

Há duas maneiras de alternar a visão web do Trident. Você pode executar um comando simples em um prompt de comando ou instalar uma versão do Office que usa o Trident por padrão. Recomendamos o primeiro método. Mas você deve usar o segundo nos cenários a seguir.

• Seu projeto foi desenvolvido com o Visual Studio e o IIS. Não é baseado Node.js.
• Você deseja ser absolutamente robusto em seus testes.
• Se por algum motivo a ferramenta de linha de comando não funcionar.

Alternar pela linha de comando

Se o seu projeto for baseado em Node.js (ou seja, não desenvolvido com o Visual Studio e o IIS (servidor de informações da Internet)), você poderá forçar o Office no Windows a usar o controle Webview do EdgeHTML fornecido pelo Edge Legacy ou o controle de webview trident fornecido pela Internet Explorer executar suplementos, mesmo que você tenha uma combinação de versões do Windows e do Office que normalmente usariam uma visão da Web mais recente. Para obter mais informações sobre quais navegadores e visões da Web são usados por várias combinações de versões do Windows e do Office, consulte Navegadores e controles webview usados pelos Suplementos do Office.

Observação

A ferramenta usada para forçar a alteração no Webview só tem suporte no canal de assinatura Beta do Microsoft 365. Ingresse no programa Do Microsoft 365 Insider e selecione a opção Canal Beta para acessar builds do Office Beta. Consulte também Sobre o Office: qual versão do Office estou usando?.

Estritamente, é a opção webview dessa ferramenta (consulte Etapa 2) que requer o canal Beta. A ferramenta tem outros comutadores que não têm esse requisito.

1. Se o projeto não foi criado com a ferramenta gerador Yeoman para Suplementos do Office , você precisará instalar a ferramenta office-addin-dev-settings. Execute o comando a seguir em um prompt de comando.

   npm install office-addin-dev-settings --save-dev
   

   Importante

   A ferramenta office-addin-dev-settings não tem suporte no Mac.

2. Especifique a visão da Web que você deseja que o Office use com o comando a seguir em um prompt de comando na raiz do projeto. Substitua <path-to-manifest> pelo caminho relativo, que é apenas o nome do arquivo de manifesto se ele estiver na raiz do projeto. Substitua por <webview> ou edge-legacyie . Observe que as opções são nomeadas em homenagem aos navegadores nos quais as visões da Web se originaram. A ie opção significa "Trident" e a opção edge-legacy significa "EdgeHTML".

   npx office-addin-dev-settings webview <path-to-manifest> <webview>
   

   Apresentamos um exemplo a seguir.

   npx office-addin-dev-settings webview manifest.xml ie
   

   Você deve ver uma mensagem na linha de comando de que o tipo de webview agora está definido como IE (ou Edge Legacy).

3. Quando terminar, defina o Office para retomar usando o webview padrão para sua combinação de versões do Windows e do Office com o comando a seguir.

   npx office-addin-dev-settings webview <path-to-manifest> default
   

Instalar uma versão do Office que usa Explorer da Internet

Use o procedimento a seguir para instalar uma versão do Office (baixada de uma assinatura do Microsoft 365) que usa o Versão Prévia do Microsoft Edge Webview (EdgeHTML) para executar suplementos ou uma versão que usa o Explorer da Internet (Trident).

1. Em qualquer aplicativo do Office, abra a guia Arquivo na faixa de opções e selecione Conta ou Conta do Office. Selecione o botão Sobre nome do host (por exemplo, Sobre Word).

2. Na caixa de diálogo aberta, localize o número completo de build xx.x.xxxxx.xxxxx e faça uma cópia dele em algum lugar.

3. Baixar a Ferramenta de Implantação do Office.

4. Execute o arquivo baixado para extrair a ferramenta. Você deve escolher onde instalar a ferramenta.

5. Na pasta em que você instalou a ferramenta (onde o setup.exe arquivo está localizado), crie um arquivo de texto com o nome config.xml e adicione o conteúdo a seguir.

   <Configuration>
     <Add OfficeClientEdition="64" Channel="SemiAnnual" Version="16.0.xxxxx.xxxxx">
       <Product ID="O365ProPlusRetail">
         <Language ID="en-us" />
       </Product>
     </Add>
   </Configuration>
   

6. Altere o Version valor.

   • Para instalar uma versão que usa EdgeHTML, altere-a para 16.0.11929.20946.
   • Para instalar uma versão que usa o Trident, altere-a para 16.0.10730.20348.

7. Opcionalmente, altere o valor de OfficeClientEdition para "32" instalar o Office de 32 bits e altere o valor conforme necessário para instalar o Language ID Office em um idioma diferente.

8. Abra um prompt de comando como administrador.

9. Navegue até a pasta com os setup.exe arquivos e config.xml .

10. Execute o seguinte comando:

    setup.exe /configure config.xml
    

    Esse comando instala o Office. Esse processo pode demorar alguns minutos.

11. Desmarque o cache do Office.

Importante

Após a instalação, desative a atualização automática do Office para que o Office não seja atualizado para uma versão que não use a visão da Web com a qual você deseja trabalhar antes de concluir o uso. Isso pode acontecer em poucos minutos de instalação. Siga estas etapas.

1. Inicie qualquer aplicativo do Office e abra um novo documento.
2. Abra a guia Arquivo na faixa de opções e selecione Conta do Office ou Conta.
3. Na coluna Informações do Produto, selecione Opções de Atualização e selecione Desabilitar Atualizações. Se essa opção não estiver disponível, o Office já está configurado para não ser atualizado automaticamente.

Quando terminar de usar a versão antiga do Office, reinstale sua versão mais recente editando o config.xml arquivo e alterando o para o Version número de build copiado anteriormente. Em seguida, repita o setup.exe /configure config.xml comando em um prompt de comando de administrador. Opcionalmente, habilite novamente as atualizações automáticas.

Confira também

• Inspecionar executando JavaScript com o Depurador
• Usando as ferramentas de desenvolvedor F12