在 Visual Studio Code 中调试 SharePoint 框架解决方案

Visual Studio Code 是频繁用于生成 SharePoint Framework 解决方案的热门代码编辑器。 通过在 Visual Studio Code 中设置对 SharePoint 框架解决方案的调试，可以更高效地对代码进行逐步调试并修复错误。

你还可以在 Microsoft 365 平台社区 (PnP) YouTube 频道上观看此视频，以查看在 Visual Studio Code 中启用调试所需的步骤：

先决条件

配置 Visual Studio Code (VS Code) 以调试SharePoint 框架解决方案的最简单方法是使用 VS Code 中包含的 JavaScript 调试器调试 Chrome & Edge。

还需要 Google Chrome 或 Microsoft Edge。

调试配置

你可以在 Visual Studio Code 工作区文件夹下的 /vscode/launch.json 文件中找到调试配置。

配置断点

1. 在 Visual Studio Code 中，打开主 Web 部件源文件，并通过选择行号左侧的边距或在编辑器中突出显示代码行并选择 F9 键在 render() 方法的第一行中添加断点。

   

2. 在 Visual Studio Code 的“视图”菜单中，选择“集成终端”选项或在键盘上选择 “CTRL+”+`。

3. 在终端中运行以下命令：

   gulp serve --nobrowser
   

   运行此命令将生成你的 SharePoint 框架解决方案，并启动本地 Web 服务器来提供输出文件。 由于调试器将启动自己的浏览器实例，因此，使用 --nobrowser 参数阻止 serve 任务打开浏览器窗口。

   

在 Visual Studio Code 中开始调试

完成 GULP 任务后，将焦点移到 Visual Studio Code 的代码区并选择 F5（或在“调试”菜单中选择“开始调试”选项）。

Visual Studio Code 中的调试模式将启动，同时将状态栏的颜色更改为橙色，并打开 Google Chrome 的新窗口，显示 SharePoint 工作台。

注意

此时已禁用断点，因为尚未加载 Web 部件的代码。 只有在将 Web 部件添加到页面后，SharePoint 框架才会根据需要加载它们。

向画布添加 Web 部件

若要验证调试是否正在运行，请在工作台中将你的 Web 部件添加到画布。

请注意，代码加载到页面后，断点指示器更改为活动状态。

如果现在重新加载页面，将命中 Visual Studio Code 中的断点，并且你将可以检查所有属性并对代码进行逐步调试。

使用托管工作台调试解决方案

生成与 SharePoint 进行通信的 SharePoint 框架解决方案时，你可能要在 SharePoint 中验证解决方案的交互情况。 可以使用托管的 SharePoint 工作台版本（可通过 https://yourtenant.sharepoint.com/_layouts/workbench.aspx 在每个 Microsoft 365 租户上获取）轻松完成此操作。

生成 SharePoint 框架解决方案时，将定期执行此类测试，并且最好为 SharePoint 工作台的托管版本创建单独的调试配置。

使用托管工作台调试 Web 部件解决方案

1. 打开 .vscode/launch.json 并更新 SharePoint 网站 URL 的“托管工作台”配置下的 url 属性。

   "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
   

2. 在 Visual Studio Code 中，激活“调试”窗格并在“配置”列表中选择新添加的“托管工作台”配置。

   

3. 通过选择 F5 或从“调试”菜单选择“开始调试”选项以开始调试。 Visual Studio Code 将切换到调试模式（使用橙色状态栏表示），并且 Debugger for Chrome 扩展将通过 Microsoft 365 登录页打开新的 Google Chrome 实例。

   

4. 登录后，将 Web 部件添加到画布并刷新工作台。 你会看到 Visual Studio Code 中的断点被命中，还能检查变量并逐步调试代码。

   

使用托管工作台调试扩展解决方案

在托管工作台中调试扩展的步骤与调试 Web 部件的步骤类似，但存在一些主要区别。

1. 打开 .vscode/launch.json 并更新 SharePoint 网站 URL 的“托管工作台”配置下的 url 属性。

   "url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
   

2. 在 Visual Studio Code 中，激活“调试”窗格并在“配置”列表中选择新添加的“托管工作台”配置。

   

3. 在终端中初始化 gulp serve 后，通过选择 F5 或从“调试”菜单选择“开始调试”选项以开始调试。 Visual Studio Code 将切换到调试模式（使用橙色状态栏表示），并且 Debugger for Chrome 扩展将通过 Microsoft 365 登录页打开新的 Google Chrome 实例。

   

4. 在浏览器中打开的工作台选项卡中，导航至想要测试扩展的 SharePoint Online 页。

5. 将以下查询字符串参数追加到 URL。 请注意，需要将 ID 更新为与自己的扩展标识符一致。 可以从 HelloWorldApplicationCustomizer.manifest.json 文件中获取此 ID。

   谨慎

   为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

   ?loadSPFX=true
   &debugManifestsFile=https://localhost:4321/temp/manifests.js
   &customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{
       "location":"ClientSideExtension.ApplicationCustomizer",
       "properties":{
         "testMessage":"Hello as property!"
       }
   }}
   

   有关 URL 参数的更多详细信息：

   • loadSPFX=true：确保 SharePoint 框架在此页面上加载。 出于性能原因，除非至少有一个扩展进行注册，否则不会加载框架。 由于尚未注册任何组件，因此必须显式加载框架。
   • debugManifestsFile：指定要加载在本地获得服务的 SPFx 组件。 加载程序只在应用程序目录（对于已部署的解决方案）和 SharePoint 清单服务器（对于系统库）中查找组件。
   • customActions：模拟自定义操作。 在网站中部署和注册此组件时，将创建这个 CustomAction 对象，并描述可以对它设置的所有不同属性。
     • Key：将扩展的 Guid 用作关联自定义操作的键。 它必须与扩展的 ID 值（可以从扩展 manifest.json 文件中获取）一致。
     • Location：自定义操作的类型。 对应用自定义工具扩展使用 ClientSideExtension.ApplicationCustomizer。
     • Properties：可选 JSON 对象，其中包含可通过 this.properties 成员获取的属性。 在此 HelloWorld 示例中，它定义了 testMessage 属性。

   完整的 URL 应如下所示：

   谨慎

   为了便于阅读，已将换 & 行缩进添加到以下代码片段。 以下文本应处于无空格的同一行。

   https://contoso.sharepoint.com/Lists/Contoso/AllItems.aspx
       ?loadSPFX=true
       &debugManifestsFile=https://localhost:4321/temp/manifests.js
       &customActions={"e5625e23-5c5a-4007-a335-e6c2c3afa485":{
           "location":"ClientSideExtension.ApplicationCustomizer",
           "properties":{
             "testMessage":"Hello as property!"
           }
       }}
   

6. 选择“加载调试脚本”，以继续从本地主机加载脚本。

   

   当页面加载时，你现在应该可以看到页面上的扩展 (列表视图命令扩展) ：

   

   此外，还可以切换断点并逐步执行代码：

   

使用 Microsoft Edge 或更早项目进行调试

如果使用的是较早版本的 SharePoint 框架 Yeoman 生成器或者想要使用 Microsoft Edge 进行调试，请按照这些步骤手动创建 launch.json 文件。

注意

若要使用 Microsoft Edge 进行调试，你必须安装 Windows 10 2018 年 4 月更新，其中包含 Microsoft Edge DevTools 协议。

为托管的工作台创建调试配置

1. 在 Visual Studio Code 中打开 .vscode/launch.json 文件。

2. 对于 Edge，复制现有的调试配置并使用托管的工作台的 URL：

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Hosted workbench",
         "type": "msedge",
         "request": "launch",
         "url": "https://contoso.sharepoint.com/_layouts/workbench.aspx",
         "webRoot": "${workspaceRoot}",
         "sourceMaps": true,
         "sourceMapPathOverrides": {
           "webpack:///.././src/*": "${webRoot}/src/*",
           "webpack:///../../../src/*": "${webRoot}/src/*",
           "webpack:///../../../../src/*": "${webRoot}/src/*",
           "webpack:///../../../../../src/*": "${webRoot}/src/*"
         }
       }
     ]
   }
   

3. 对于 Chrome，复制现有的调试配置并使用托管的工作台的 URL：

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Hosted workbench",
         "type": "pwa-chrome",
         "request": "launch",
         "url": "https://contoso.sharepoint.com/_layouts/workbench.aspx",
         "webRoot": "${workspaceRoot}",
         "sourceMaps": true,
         "sourceMapPathOverrides": {
           "webpack:///.././src/*": "${webRoot}/src/*",
           "webpack:///../../../src/*": "${webRoot}/src/*",
           "webpack:///../../../../src/*": "${webRoot}/src/*",
           "webpack:///../../../../../src/*": "${webRoot}/src/*"
         },
         "runtimeArgs": [
           "--remote-debugging-port=9222",
           "-incognito"
         ]
       }
     ]
   }
   

另请参阅

• 如何调试 SharePoint 框架 Web 部件 (Elio Struyf)
• 使用 Visual Studio Code (Velin Georgiev) 调试 SPFx React Web 部件
• SharePoint 框架的 Yeoman 生成器
• SharePoint 框架概述