Depurar seu suplemento com o log de tempo de execução

Artigo
07/16/2024

Você pode usar o log de tempo de execução para depurar o manifesto do seu suplemento, assim como diversos erros de instalação. Esse recurso pode ajudá-lo a identificar e corrigir problemas com seu manifesto que não são detectados pela validação de esquema XSD, como uma incompatibilidade entre as identificações dos recursos. O registo de runtime é particularmente útil para depurar suplementos que implementam comandos de suplementos e funções personalizadas do Excel.

Observação

A funcionalidade de registo de runtime está atualmente disponível para o Office 2016 ou posterior no ambiente de trabalho.

Importante

o log do tempo de execução afeta o desempenho. Ative-o somente quando precisar depurar problemas com o manifesto do suplemento.

Use o log de tempo de execução na linha de comandos

Habilitar o log de tempo de execução na linha de comando é a maneira mais rápida de usar essa ferramenta de log. Esse usa npx, que é fornecido por padrão como parte do npm@5.2.0+. Se você possui uma versão anterior do npm, tente as instruções do Log de tempo de execução no Windows ou do Log de tempo de execução no Mac, ou instale o npx.

Importante

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

Para habilitar o log de tempo de execução:

npx office-addin-dev-settings runtime-log --enable

Para habilitar o log de tempo de execução apenas para um arquivo específico, use o mesmo comando com um nome de arquivo:
```
npx office-addin-dev-settings runtime-log --enable [filename.txt]
```

Para desabilitar o log de tempo de execução:

npx office-addin-dev-settings runtime-log --disable

Para exibir se o log de tempo de execução está ativado:
```
npx office-addin-dev-settings runtime-log
```
Para exibir ajuda na linha de comandos para o log de tempo de execução:
```
npx office-addin-dev-settings runtime-log --help
```

Log de tempo de execução no Windows

Verifique se você está executando o Office 2016 para área de trabalho na compilação 16.0.7019 ou posterior.
Adicione a chave do registro RuntimeLogging em HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\Developer\
Observação

Se a Developer chave (pasta) ainda não existir HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\em , conclua os seguintes passos para criá-la.
1. Clique com o botão direito do rato (ou selecione sem soltar) a chave WEF (pasta) e selecione Nova>Chave.
2. Nomeie a nova chave como Developer.
Defina o valor padrão da chave RuntimeLogging para o caminho completo do arquivo em que você deseja que o log seja gravado. O exemplo seguinte executado num .reg ficheiro define o registo para a C:\ClientLogs\log.txt pasta .
```
[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\RuntimeLogging]
@="C:\\ClientLogs\\log.txt"`
```
Observação

A pasta na qual o arquivo de log será gravado deverá existir e você precisará ter permissões de gravação.

A imagem a seguir mostra qual deve ser a aparência do registro. Para desativar o recurso, remova a chave do registro RuntimeLogging.

O editor de registo com uma chave de registo RuntimeLogging.

Log de tempo de execução no Mac

Certifique-se de que está a executar a versão 16.27.19071500 ou posterior do Office 2016.
Abra o Terminal e defina uma preferência de log de tempo de execução usando o comando defaults:
```
defaults write <bundle id> CEFRuntimeLoggingFile -string <file_name>
```
<bundle id> identifica quais hosts devem ser habilitados no log de tempo de execução. <file_name> é o nome do arquivo de texto no qual o log será gravado.

Defina <bundle id> para um dos seguintes valores para ativar o registo de runtime para a aplicação correspondente.
- com.microsoft.Word
- com.microsoft.Excel
- com.microsoft.Powerpoint
- com.microsoft.Outlook

O exemplo seguinte ativa o registo de runtime para o Word e, em seguida, abre o ficheiro de registo.

defaults write com.microsoft.Word CEFRuntimeLoggingFile -string "runtime_logs.txt"
open ~/library/Containers/com.microsoft.Word/Data/runtime_logs.txt

Observação

Será preciso reiniciar o Office depois de executar o comando defaults para habilitar o log de tempo de execução.

Para desativar o log de tempo de execução, use o comando defaults delete:

defaults delete <bundle id> CEFRuntimeLoggingFile

O exemplo seguinte desativará o registo de runtime para o Word.

defaults delete com.microsoft.Word CEFRuntimeLoggingFile

Use o log do tempo de execução para solucionar problemas em seu manifesto

Para usar o log do tempo de execução para solucionar problemas ao carregar um suplemento:

Realize o sideload do seu suplemento para teste.

Observação

Recomendamos realizar o sideload apenas do suplemento que você está testando para minimizar a quantidade de mensagens no arquivo de log.
Se nada acontecer e você não vir seu suplemento (e ele não estiver aparecendo na caixa de diálogo de suplementos), abra o arquivo de log.
Procure pela ID de seu suplemento no arquivo de log, definida no seu manifesto. No arquivo de log, essa ID está marcada como SolutionId.

Problemas conhecidos com o log de tempo de execução

Talvez você veja mensagens no arquivo de log que são confusas ou que estão classificadas incorretamente. Por exemplo:

A mensagem Medium Current host not in add-in's host list seguida por Unexpected Parsed manifest targeting different host é incorretamente classificada como um erro.
Se você vir a mensagem Unexpected Add-in is missing required manifest fields DisplayName e ela não contiver uma SolutionId, o erro provavelmente não está relacionado ao suplemento que você está depurando.
Qualquer mensagem Monitorable indica erros esperados do ponto de vista do sistema. Às vezes, indica um problema com o seu manifesto, como um elemento que foi soletrado incorretamente e que foi ignorado, mas que não fez com que o manifesto falhasse.

Compartilhar via