Depurar suplementos com ferramentas de programador no Internet Explorer

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

• Não pode, ou não pretende, depurar com ferramentas incorporadas no seu IDE; ou encontra um problema que só ocorre quando o suplemento é executado fora do IDE.
• O seu computador está a utilizar uma combinação de versões do Windows e do Office que utilizam o controlo webview do Internet Explorer, Trident.

Para determinar que browser ou webview está a ser utilizado no seu computador, consulte Browsers e controlos webview utilizados pelos Suplementos do Office.

Dica

Nas versões recentes do Office, uma forma de identificar o controlo webview que o Office está a utilizar é através do menu de personalidade em qualquer suplemento onde esteja disponível. (O menu de personalidade não é suportado 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 reporta o Microsoft Edge, o Microsoft Edge Legado ou o 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 utiliza o Trident ou para forçar a sua versão atual a utilizar o Trident, consulte Mudar para o Webview Trident.

Depurar um suplemento do painel de tarefas com as ferramentas F12

O Windows 10 e 11 incluem uma ferramenta de desenvolvimento Web denominada "F12" porque foi originalmente iniciada ao premir F12 no Internet Explorer. F12 é agora uma aplicação independente utilizada para depurar o suplemento quando está em execução no controlo webview do Internet Explorer, Trident. A aplicação 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 é executada num processo de runtime do browser oculto ao qual as ferramentas F12 não conseguem detetar ou anexar, pelo que a técnica descrita neste artigo não pode ser utilizada para depurar código na função.

Os passos seguintes são as instruções para depurar o suplemento. Se apenas quiser testar as ferramentas F12, veja Suplemento de exemplo para testar as ferramentas F12.

1. Faça sideload e execute 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 a depurar. O seu suplemento será apresentado na janela com o nome do nome de ficheiro da home page do suplemento. Na captura de ecrã seguinte, é Home.html. Só são apresentados os processos em execução no Internet Explorer ou tridente. A ferramenta não pode anexar a processos em execução noutros browsers ou webviews, incluindo o Microsoft Edge.

   

3. Selecione o processo do suplemento; ou seja, o nome do ficheiro da home page. Esta ação irá anexar as ferramentas F12 ao processo e abrir a interface de utilizador F12 principal.

4. Abra a guia Depurador.

5. No canto superior esquerdo do separador, logo abaixo do friso da ferramenta de depurador, existe um pequeno ícone de pasta. Selecione esta opção para abrir uma lista pendente dos ficheiros no suplemento. Apresentamos um exemplo a seguir.

   

6. Selecione o ficheiro que pretende depurar e este é aberto no painel script (à esquerda) do separador Depurador . Se estiver a utilizar um transpiler, bundler ou minifier, que altera o nome do ficheiro, terá o nome final que está realmente carregado e não o nome do ficheiro de origem original.

7. Desloque-se para uma linha onde pretende definir um ponto de interrupção e clique na margem à esquerda do número da linha. Verá um ponto vermelho à esquerda da linha e será apresentada uma linha correspondente no separador Pontos de interrupção do painel inferior direito. A seguinte captura de ecrã é 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, é apresentada uma seta para a direita no ponto vermelho do ponto de interrupção. A seguinte captura de ecrã é um exemplo.

   

Dica

Para obter mais informações sobre como utilizar as ferramentas F12, veja Inspecionar a execução de JavaScript 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 Base e, em seguida, selecione Obter Suplementos.>
3. Na caixa de diálogo Suplementos do Office , selecione o separador LOJA .
4. Selecione o suplemento QR4Office . É aberto num painel de tarefas.
5. Inicie as ferramentas de desenvolvimento F12 que correspondem à sua versão do Office, conforme descrito na secção anterior.
6. Na janela F12, selecione Home.html.
7. No separador Depurador , abra o ficheiro Home.js conforme descrito na secçã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 num suplemento

Se o seu suplemento utilizar a API de Caixa de Diálogo do Office, a caixa de diálogo é executada num processo separado do painel de tarefas (se existir) e as ferramentas têm de ser anexadas a esse processo. Siga estas etapas.

1. Execute o suplemento e as ferramentas.
2. Abra a caixa de diálogo e, em seguida, selecione o botão Atualizar nas ferramentas. O processo de caixa de diálogo é apresentado. O nome é o nome de ficheiro do ficheiro que está aberto na caixa de diálogo.
3. Selecione o processo para o abrir e depurar, tal como descrito na secção Depurar um suplemento do painel de tarefas com as ferramentas F12.

Mudar para a vista Web tridente

Existem duas formas de mudar o Webview Trident. Pode executar um comando simples numa linha de comandos ou pode instalar uma versão do Office que utiliza o Trident por predefinição. Recomendamos o primeiro método. No entanto, deve utilizar o segundo nos seguintes cenários.

• O seu projeto foi desenvolvido com o Visual Studio e o IIS. Não se baseia Node.js.
• Quer ser absolutamente robusto nos seus testes.
• Se, por algum motivo, a ferramenta de linha de comandos não funcionar.

Alternar através da linha de comandos

Se o seu projeto for baseado em Node.js (ou seja, não for desenvolvido com o Visual Studio e o servidor de Informação Internet (IIS)), pode forçar o Office no Windows a utilizar o controlo webview edgeHTML fornecido pelo Edge Legado ou o controlo de webview Trident fornecido pelo Internet Explorer para executar suplementos, mesmo que tenha uma combinação de versões do Windows e do Office que normalmente utilizaria uma descrição Web mais recente. Para obter mais informações sobre que browsers e webviews são utilizados por várias combinações de versões do Windows e do Office, consulte Browsers e controlos webview utilizados pelos Suplementos do Office.

Observação

A ferramenta utilizada para forçar a alteração no Webview só é suportada no canal de subscrição Beta do Microsoft 365. Adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações do Office Beta. Consulte também Acerca do Office: Que versão do Office estou a utilizar?.

Estritamente, é a webview mudança desta ferramenta (consulte o Passo 2) que requer o canal Beta. A ferramenta tem outros comutadores que não têm este requisito.

1. Se o seu projeto não tiver sido criado com a ferramenta Gerador Yeoman para Suplementos do Office , tem de instalar a ferramenta office-addin-dev-settings. Execute o seguinte comando numa linha de comandos.

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

   Importante

   A ferramenta office-addin-dev-settings não é suportada no Mac.

2. Especifique o webview que pretende que o Office utilize com o seguinte comando numa linha de comandos na raiz do projeto. Substitua <path-to-manifest> pelo caminho relativo, que é apenas o nome do ficheiro de manifesto se estiver na raiz do projeto. Substitua por <webview> ou edge-legacyie . Tenha em atenção que as opções têm o nome dos browsers nos quais as webviews tiveram origem. A ie opção significa "Trident" e a opção edge-legacy significa "EdgeHTML".

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

   Eis alguns exemplos.

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

   npx office-addin-dev-settings webview manifest.json edge-legacy
   

   Deverá ver uma mensagem na linha de comandos a indicar que o tipo de webview está agora definido como IE (ou Edge Legado).

3. Quando tiver terminado, defina o Office para retomar a utilização da vista Web predefinida para a sua combinação de versões do Windows e do Office com o seguinte comando.

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

Instalar uma versão do Office que utiliza o Internet Explorer

Utilize o procedimento seguinte para instalar uma versão do Office (transferida a partir de uma subscrição do Microsoft 365) que utiliza o Microsoft Edge Legacy Webview (EdgeHTML) para executar suplementos ou uma versão que utiliza o Internet Explorer (Trident).

1. Em qualquer aplicação do Office, abra o separador Ficheiro no friso e, em seguida, selecione Conta ou Contado Office. Selecione o botão Acerca do nome do anfitrião (por exemplo, Acerca do Word).

2. Na caixa de diálogo que é aberta, localize o número de compilação xx.x.xxxxx.xxxxx completo e faça uma cópia do mesmo algures.

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

4. Execute o ficheiro transferido para extrair a ferramenta. É-lhe pedido para escolher onde instalar a ferramenta.

5. Na pasta onde instalou a ferramenta (onde se encontra o setup.exe ficheiro), crie um ficheiro de texto com o nome config.xml e adicione os seguintes conteúdos.

   <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 utiliza o EdgeHTML, altere-a para 16.0.11929.20946.
   • Para instalar uma versão que utiliza o Trident, altere-a para 16.0.10730.20348.

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

8. Abra uma linha de comandos como administrador.

9. Navegue para a pasta com os setup.exe ficheiros e config.xml .

10. Execute o seguinte comando:

    setup.exe /configure config.xml
    

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

11. Limpe a cache do Office.

Importante

Após a instalação, certifique-se de que desativa a atualização automática do Office, para que o Office não seja atualizado para uma versão que não utilize a vista Web com a qual pretende trabalhar antes de concluir a sua utilização. Isto pode ocorrer a poucos minutos da instalação. Siga estas etapas.

1. Inicie uma aplicação do Office e abra um novo documento.
2. Abra o separador Ficheiro no friso e, em seguida, selecione Conta do Office ou Conta.
3. Na coluna Informações do Produto , selecione Opções de Atualização e, em seguida, selecione Desativar Atualizações. Se essa opção não estiver disponível, o Office já está configurado para não atualizar automaticamente.

Quando terminar de utilizar a versão antiga do Office, reinstale a sua versão mais recente ao editar o config.xml ficheiro e ao alterar o Version para o número de compilação que copiou anteriormente. Em seguida, repita o setup.exe /configure config.xml comando numa linha de comandos de administrador. Opcionalmente, reativar as atualizações automáticas.

Confira também

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