使用运行时日志记录功能调试加载项

  • 项目

可以使用运行时日志记录调试加载项的清单以及多个安装错误。 此功能可以帮助你标识并修复清单中未被 XSD 架构验证检测到的问题，例如资源 ID 间的不匹配等。 运行时日志记录对于调试实现外接程序命令和 Excel 自定义函数的加载项特别有用。

注意

运行时日志记录功能目前可用于桌面版 Office 2016 或更高版本。

重要

运行时日志记录影响性能。 请仅在需要调试外接程序清单中的问题时启用此功能。

使用命令行中的运行时日志

从命令行启用运行时日志记录是最快的使用此日志记录工具的方式。 这些使用 npx，默认情况下，它作为 npm@5.2.0+ 的一部分提供。 如果使用的是 npm 的早期版本，请尝试 Windows 上的运行时日志记录或 Mac说明，或者安装 npx。

重要

Mac 不支持 office-addin-dev-settings 工具。

  • 要启用运行时日志记录，请执行以下操作：

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

  • 若要仅对特定文件启用运行时日志记录，请使用包含文件名的相同命令：

    npx office-addin-dev-settings runtime-log --enable [filename.txt]

  • 要禁用运行时日志记录，请执行以下操作：

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

  • 要显示是否启用了运行时日志记录，请执行以下操作：

    npx office-addin-dev-settings runtime-log

  • 要在命令行内显示有关运行时日志记录的帮助，请执行以下操作：

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

Windows 上的运行时日志记录

  1. 确保运行的是 Office 2016 桌面版 16.0.7019 或更高版本。

  2. 在 HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\Developer\ 下添加 RuntimeLogging 注册表项。

    注意

    Developer如果在 下HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\尚不存在 (文件夹) 键，请完成以下步骤来创建它。

    1. 右键单击 WEF 密钥（文件夹），然后选择新建>密钥。
    2. 将新密钥命名为 Developer。

  3. 将 RuntimeLogging 项的默认值设置为你想要在其中写入日志的文件的完整路径。 以下示例在文件中 .reg 运行，将日志记录设置为 C:\ClientLogs\log.txt 文件夹。

    [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\RuntimeLogging]
@="C:\\ClientLogs\\log.txt"`

    注意

    向其中写入日志文件的目录必须已经存在，并且必须拥有对它的写入权限。

注册表应如下图所示。 若要禁用此功能，请从注册表中删除 RuntimeLogging。

具有 RuntimeLogging 注册表项的注册表编辑器。

Mac 上的运行时日志记录

  1. 请确保运行的是 Office 2016 桌面版本 16.27.19071500 或更高版本。

  2. 打开终端并使用 defaults 命令设置运行时日志记录首选项：

    defaults write <bundle id> CEFRuntimeLoggingFile -string <file_name>

    <bundle id> 确定了主机要对哪些运行时日志记录。 <file_name> 是要将日志写入的文本文件的名称。

    设置为 <bundle id> 以下值之一，以启用相应应用程序的运行时日志记录。

    • com.microsoft.Word
    • com.microsoft.Excel
    • com.microsoft.Powerpoint
    • com.microsoft.Outlook

以下示例为Word启用运行时日志记录，然后打开日志文件。

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

注意

运行 defaults 命令来启用运行时日志记录后，需要重启 Office。

要关闭运行时日志记录，请使用 defaults delete 命令：

defaults delete <bundle id> CEFRuntimeLoggingFile

以下示例将关闭Word的运行时日志记录。

defaults delete com.microsoft.Word CEFRuntimeLoggingFile

使用运行时日志记录功能排查清单问题

若要使用运行时日志记录功能排查加载项的加载问题，请执行以下操作：

  1. 旁加载加载项以供测试。

    注意

    建议仅旁加载要测试的加载项，以最大限度地减少日志文件中的消息数。

  2. 如果没有任何变化，且看不到加载项（加载项对话框中没有显示），请打开日志文件。

  3. 在日志文件中搜索你的外接程序 ID（已在清单中定义）。 在日志文件中，此 ID 标有 SolutionId。

运行时日志记录已知问题

在日志文件中看到的信息可能很混乱或其分类不正确。 例如：

  • 后跟 Medium Current host not in add-in's host list 的信息 Unexpected Parsed manifest targeting different host 是错误分类为错误。

  • 如果发现信息 Unexpected Add-in is missing required manifest fields DisplayName 且其不包含 SolutionId，则此错误极可能与你正在调试的外接程序无关。

  • 对系统而言，任何 Monitorable 信息都会视其为错误。 有时这些信息表示清单中的问题，例如一个已跳过但未引起清单运行失败的拼写错误的元素。

另请参阅