使用基于 Visual Studio Code 和 Microsoft Edge WebView2 (Chromium) 在 Windows 上调试 Office 加载项

项目
04/15/2024

在 Windows 上运行的 Office 加载项可以直接在 Visual Studio Code 中针对 Edge Chromium WebView2 运行时进行调试。

重要

本文仅适用于 Office 在 Microsoft Edge Chromium WebView2 运行时中运行加载项时，如 Office 外接程序使用的浏览器和 Webview 控件中所述。有关使用原始 WebView (EdgeHTML) 运行时针对Microsoft Edge 旧版进行Visual Studio Code调试的说明，请参阅使用 Microsoft Edge 旧版中的开发人员工具调试加载项。

提示

如果无法使用或不希望使用 Visual Studio Code 内置的工具进行调试;或者遇到仅在加载项在 Visual Studio Code 外部运行时出现的问题，可以使用基于 Edge (Chromium) 开发人员工具调试 Edge Chromium WebView2 运行时，如中所述使用适用于 Microsoft Edge WebView2 的开发人员工具调试加载项。

此调试模式是动态的，允许在代码运行时设置断点。在附加调试器时立即查看代码中的更改，所有这些操作不会丢失调试会话。代码更改也会持续存在，因此将看到对代码进行多次更改的结果。下图显示此扩展正在运行。

Office 加载项调试器扩展调试 Excel 加载项的一部分。

先决条件

Visual Studio Code
Node.js （版本 10+）
Windows 10、11
平台和 Office 应用程序的组合，支持 Microsoft Edge 与基于 WebView2 (Chromium 的) ，如 Office 外接程序使用的浏览器和 Webview 控件中所述。如果 Microsoft 365 订阅中的 Office 版本早于版本 2101，则需要安装 WebView2。有关安装 WebView2 的说明，请参阅 Microsoft Edge WebView2/嵌入 Web 内容...与 Microsoft Edge WebView2。

调试使用 Yo Office 创建的项目

这些说明假定你在使用适用于 Office 加载项的 Yeoman 生成器之前拥有使用命令行的经验，了解基本 JavaScript，并且已创建过 Office 加载项项目。如果你之前没有这样做过，请考虑访问我们的其中一个教程，例如 Excel Office 加载项教程。

第一步取决于项目及其创建方式。
- 如果要创建一个项目来试验Visual Studio Code中的调试，请使用 Office 加载项的 Yeoman 生成器。遵循任何 Yo Office 快速入门指南，例如 Outlook 加载项快速入门。
- 如果要调试使用 Yo Office 创建的现有项目，请跳到下一步。
打开 VS Code 并在其中打开项目。
选择“ 查看>运行” 或输入 Ctrl+Shift+D 以切换到调试视图。
从“运行并调试”选项中，为主机应用程序选择 Edge Chromium 选项，例如“Outlook 桌面版（Edge Chromium）”。选择 F5 或从菜单中选择 “运行>开始调试 ”以开始调试。此操作在节点窗口中自动启动本地服务器以托管加载项，然后自动打开主机应用程序，例如 Excel 或 Word。这可能需要几秒钟的时间。
提示

如果不使用通过 Yo Office 创建的项目，系统可能会提示调整注册表项。项目根文件夹下，在命令行中运行以下命令：。
```
npx office-addin-debugging start <your manifest path>
```
重要

如果项目是使用较旧版本的 Yo Office 创建的，则在开始调试大约 10 - 30 秒后，可能会看到以下错误对话框（此时可能已执行此过程中的另一步），并且可能隐藏在下一步中所述的对话框后面。

完成附录中的任务，然后重启此过程。
在主机应用程序中，加载项现已可供使用。选择 显示任务窗格 或运行其他加载项命令。系统将显示一个对话框，其中包含类似于以下内容的文本：

WebView 停止加载。要调试 webview，请使用适用于 Microsoft Edge 扩展的 Microsoft 调试器将 VS 代码附加到 webview 实例，然后单击“确定”以继续。要防止今后出现此对话框，单击“取消”。

选择“确定”。

注意

如果选择“取消”，则当加载项的此实例正在运行时，将不会再次显示该对话框。但如果重新启动加载项，则会再次看到该对话框。
现在可以在你的项目代码中设置断点并进行调试。若要在 Visual Studio Code 中设置断点，请将鼠标悬停在代码行旁边，然后选择显示的红色圆圈。
在加载项中运行调用断点行的功能。你将看到已命中断点，可以检查局部变量。

注意

Office.initialize 或 Office.onReady 调用中的断点将被忽略。有关这些函数的详细信息，请参阅初始化 Office 加载项。

重要

停止调试会话的最佳方法是选择 Shift+F5 或从菜单中选择 “运行>停止调试 ”。此操作应关闭节点服务器窗口并尝试关闭主机应用程序，但主机应用程序上会出现提示，询问是否保存文档。请做出适当选择，让主机应用程序关闭。避免手动关闭节点窗口或主机应用程序。这样做可能会导致 bug，尤其是在重复停止和启动调试会话时。

如果调试停止工作---例如，如果忽略断点---停止调试。然后，如有必要，关闭所有主机应用程序窗口和节点窗口。最后，关闭 Visual Studio Code 并重新将其打开。

调试未使用 Yo Office 创建的项目

如果项目不是使用 Yo Office 创建的，则需要为 Visual Studio Code 创建调试配置。

配置package.json文件

确保有文件 package.json 。如果还没有package.json文件，请在项目的根文件夹中运行 npm init 并回答提示。
运行 npm install office-addin-debugging。此包旁加载加载项进行调试。

打开 package.json文件。 scripts在部分中，添加以下脚本。

"start:desktop": "office-addin-debugging start $MANIFEST_FILE$ desktop",
"dev-server": "$SERVER_START$"

将替换为 $MANIFEST_FILE$ 清单的正确文件名和文件夹位置。
将替换为 $SERVER_START$ 命令以启动 Web 服务器。在这些步骤的后面部分，包 office-addin-debugging 将专门查找 dev-server 用于启动 Web 服务器的脚本。
保存并关闭 package.json 文件。

配置launch.json文件

在项目的 \.vscode文件夹中创建名为 launch.json 的文件（如果还没有文件夹）。

将以下 JSON 复制到文件中。

{
  // Other properties may be here.
  "configurations": [
    {
      "name": "$HOST$ Desktop (Edge Chromium)",
      "type": "msedge",
      "request": "attach",
      "useWebView": true,
      "port": 9229,
      "timeout": 600000,
      "webRoot": "${workspaceRoot}",
      "preLaunchTask": "Debug: Excel Desktop"
    }
  ]
  // Other properties may be here.
}

注意

如果已有文件 launch.json ，只需将单个配置添加到节即可 configurations 。

将占位符 $HOST$ 替换为运行外接程序的 Office 应用程序的名称。例如，Outlook 或 Word。
保存并关闭此文件。

配置tasks.json

在\.vscode项目的文件夹中创建名为 tasks.json 的文件。

将以下 JSON 复制到文件中。它包含开始调试加载项的任务。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Debug: $HOST$ Desktop",
      "type": "shell",
      "command": "npm",
      "args": ["run", "start:desktop", "--", "--app", "$HOST$"],
      "presentation": {
        "clear": true,
        "panel": "dedicated"
      },
      "problemMatcher": []
    }
  ]
}

注意

如果已有文件 tasks.json ，只需将单个任务添加到节即可 tasks 。

将占位符 $HOST$ 的两个实例替换为运行外接程序的 Office 应用程序的名称。例如，Outlook 或 Word。

现在可以使用 VS Code 调试器 (F5) 调试项目。

附录

在错误对话框中，选择"取消"按钮。
如果调试未自动停止，请选择 Shift+F5 或从菜单中选择 “运行>停止调试 ”。
如果本地服务器未自动关闭，请关闭运行本地服务器的节点窗口。
如果 Office 关闭应用程序，请关闭该应用程序。
打开项目中的 \.vscode\launch.json 文件。
在数组 configurations 中，有几个配置对象。找到其名称具有模式 $HOST$ Desktop (Edge Chromium)，其中 $HOST$ 是加载项运行的 Office 应用程序，例如 Outlook Desktop (Edge Chromium) 或 Word Desktop (Edge Chromium)。
将 "type" 属性的值从 "edge" 更改为 "pwa-msedge"。
将 "useWebView" 属性的值从字符串 "advanced" 更改为布尔值 true （请注意， true 周围没有引号）。
保存文件。
关闭 VS Code。

通过