Debug your add-in with runtime logging

Article
05/05/2023

You can use runtime logging to debug your add-in's manifest as well as several installation errors. This feature can help you identify and fix issues with your manifest that are not detected by XSD schema validation, such as a mismatch between resource IDs. Runtime logging is particularly useful for debugging add-ins that implement add-in commands and Excel custom functions.

Note

The runtime logging feature is currently available for Office 2016 or later on desktop.

Important

Runtime Logging affects performance. Turn it on only when you need to debug issues with your add-in manifest.

Use runtime logging from the command line

Enabling runtime logging from the command line is the fastest way to use this logging tool. These use npx, which is provided by default as part of npm@5.2.0+. If you have an earlier version of npm, try Runtime logging on Windows or Runtime logging on Mac instructions, or install npx.

Important

The office-addin-dev-settings tool is not supported on Mac.

To enable runtime logging:

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

To enable runtime logging only for a specific file, use the same command with a filename:
```
npx office-addin-dev-settings runtime-log --enable [filename.txt]
```

To disable runtime logging:

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

To display whether runtime logging is enabled:
```
npx office-addin-dev-settings runtime-log
```
To display help within the command line for runtime logging:
```
npx office-addin-dev-settings runtime-log --help
```

Runtime logging on Windows

Make sure that you are running Office 2016 desktop build 16.0.7019 or later.
Add the RuntimeLogging registry key under HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\Developer\.
Note

If the Developer key (folder) doesn't already exist under HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\, complete the following steps to create it.
1. Right-click (or select and hold) the WEF key (folder) and select New > Key.
2. Name the new key Developer.
Set the default value of the RuntimeLogging key to the full path of the file where you want the log to be written. The following example run in a .reg file sets the logging to the C:\ClientLogs\log.txt folder.
```
[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\RuntimeLogging]
@="C:\\ClientLogs\\log.txt"`
```
Note

The directory in which the log file will be written must already exist, and you must have write permissions to it.

The following image shows what the registry should look like. To turn the feature off, remove the RuntimeLogging key from the registry.

The registry editor with a RuntimeLogging registry key.

Runtime logging on Mac

Make sure that you are running Office 2016 desktop build 16.27.19071500 or later.
Open Terminal and set a runtime logging preference by using the defaults command:
```
defaults write <bundle id> CEFRuntimeLoggingFile -string <file_name>
```
<bundle id> identifies which the host for which to enable runtime logging. <file_name> is the name of the text file to which the log will be written.

Set <bundle id> to one of the following values to enable runtime logging for the corresponding application.
- com.microsoft.Word
- com.microsoft.Excel
- com.microsoft.Powerpoint
- com.microsoft.Outlook

The following example enables runtime logging for Word and then opens the log file.

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

Note

You'll need to restart Office after running the defaults command to enable runtime logging.

To turn off runtime logging, use the defaults delete command:

defaults delete <bundle id> CEFRuntimeLoggingFile

The following example will turn off runtime logging for Word.

defaults delete com.microsoft.Word CEFRuntimeLoggingFile

Use runtime logging to troubleshoot issues with your manifest

To use runtime logging to troubleshoot issues loading an add-in:

Sideload your add-in for testing.

Note

We recommend that you sideload only the add-in that you are testing to minimize the number of messages in the log file.
If nothing happens and you don't see your add-in (and it's not appearing in the add-ins dialog box), open the log file.
Search the log file for your add-in ID, which you define in your manifest. In the log file, this ID is labeled SolutionId.

Known issues with runtime logging

You might see messages in the log file that are confusing or that are classified incorrectly. For example:

The message Medium Current host not in add-in's host list followed by Unexpected Parsed manifest targeting different host is incorrectly classified as an error.
If you see the message Unexpected Add-in is missing required manifest fields DisplayName and it doesn't contain a SolutionId, the error is most likely not related to the add-in you are debugging.
Any Monitorable messages are expected errors from a system point of view. Sometimes they indicate an issue with your manifest, such as a misspelled element that was skipped but didn't cause the manifest to fail.

Share via