在 Visual Studio 中调试 Office 加载项
本文介绍如何在 Visual Studio 2022 中使用 Office 外接程序项目模板之一创建的 Office 外接程序中调试客户端代码。 有关在 Office 外接程序中调试服务器端代码的信息，请参阅 调试 Office 外接程序概述 - 服务器端还是客户端？。
注意
不能使用 Visual Studio 调试 Office on Mac 中的加载项。 有关在 Mac 上进行调试的信息，请参阅 在 Mac 上调试 Office 加载项。
查看生成和调试属性
在开始调试之前，请查看每个项目的属性，以确认 Visual Studio 将打开所需的 Office 应用程序，以及是否已正确设置其他生成和调试属性。
外接程序项目属性
打开外接程序项目的 “属性” 窗口以查看项目属性。
在“解决方案资源管理器”中，选择外接程序项目（而不是 Web 应用程序项目）。
在菜单栏中，依次选择“视图”>“属性窗口”。
下表介绍了外接程序项目的属性。
| 属性 | 说明 |
|---|---|
| 启动操作 | 指定外接程序的调试模式。 如果要在 Windows 上的 Microsoft 365 中调试，则应将其设置为 Office 桌面客户端 。 若要在 web 上的 Microsoft 365 中调试，应将其设置为 Microsoft Edge。 |
|
启动文档 （仅限 Excel、PowerPoint 和 Word 外接程序） |
指定要在启动项目时打开的文档。 在新项目中，此值设置为 [新建 Excel 工作簿]、 [新建 Word 文档]或 [新 PowerPoint 演示文稿] 。 若要指定特定文档，请按照 使用现有文档调试加载项中的步骤操作。 |
| Web 项目 | 指定与外接程序关联的 Web 项目的名称。 |
|
电子邮件地址 （仅限 Outlook 外接程序） |
指定你想在 Exchange Server 或 Exchange Online 中用来测试 Outlook 外接程序的用户帐户的电子邮件地址。 如果留空，在开始调试时，系统会提示输入电子邮件地址。 |
|
EWS Url （仅限 Outlook 外接程序） |
指定 Exchange Web Services URL (例如： https://www.contoso.com/ews/exchange.aspx) 。 此属性可以留空。 |
|
OWA Url （仅限 Outlook 外接程序） |
指定 Outlook 网页版 URL (例如： https://www.contoso.com/owa) 。 此属性可以留空。 |
|
使用多重身份验证 （仅限 Outlook 加载项） |
指定指示是否应使用多重身份验证的布尔值。 默认值为 false，但 属性没有实际效果。 如果通常必须提供第二个因素才能登录到电子邮件帐户，则开始调试时，系统会提示你。 |
|
用户名 （仅限 Outlook 外接程序） |
指定你想在 Exchange Server 或 Exchange Online 中用来测试 Outlook 外接程序的用户帐户的名称。 此属性可以留空。 |
| 项目文件 | 指定包含生成、配置和有关项目的其他信息的文件名称。 |
| 项目文件夹 | 指定项目文件的位置。 |
|
活动部署配置 (仅在调试 Excel 时出现， PowerPoint 或 Word 网页版) |
指定部署配置。 这应设置为 “默认”。 |
|
服务器连接 (仅在调试 Excel 时出现， PowerPoint 或 Word 网页版) |
指定项目是否连接到 网站 URL 属性中指定的 SharePoint 服务。 这应设置为 Online。 |
|
网站 URL (仅在调试 Excel 时出现， PowerPoint 或 Word 网页版) |
指定要在调试时托管外接程序页的 SharePoint 租户的完整绝对 URL。 例如 https://mysite.sharepoint.com/ |
注意
对于 Outlook 外接程序，可以选择在“属性”窗口中为一个或多个 Outlook 外接程序仅属性指定值，但不需要这样做。
Web 应用程序项目属性
打开 Web 应用程序项目的 “属性” 窗口以查看项目属性。
在 “解决方案资源管理器”中，选择 Web 应用程序项目。
在菜单栏中，依次选择“视图”>“属性窗口”。
下表介绍了与 Office 外接程序项目最相关的 Web 应用程序项目的属性。
| 属性 | 说明 |
|---|---|
| SSL 已启用 | 指定是否在站点上启用 SSL。 对于 Office 外接程序项目，此属性应设置为 True。 |
| SSL URL | 指定站点的安全 HTTPS URL。 只读。 |
| URL | 指定站点的 HTTP URL。 只读。 |
| 项目文件 | 指定包含生成、配置和有关项目的其他信息的文件名称。 |
| 项目文件夹 | 指定项目文件的位置。 只读。 Visual Studio 在运行时生成的清单文件将写入到此位置的 bin\Debug\OfficeAppManifests 文件夹中。 |
在 Windows 桌面上调试加载项项目
本部分介绍如何在 Windows 上的桌面 Office 中启动和调试加载项;即加载项项目的 “启动操作” 属性设置为 Office 桌面客户端时。
启动外接程序项目
通过从菜单栏中选择“ 调试>开始调试” 或按 F5 按钮启动项目。 Visual Studio 会自动生成解决方案并启动 Office 主机应用程序。
当 Visual Studio 生成项目时，它会执行以下任务：
创建仅外接程序清单文件的副本，并将其添加到目录中
_ProjectName_\bin\Debug\OfficeAppManifests。 在启动 Visual Studio 并调试加载项时，托管外接程序的 Office 应用程序会使用此副本。在 Windows 计算机上创建一组注册表项，使加载项显示在 Office 应用程序中。
生成 Web 应用程序项目，然后将其部署到本地 IIS Web 服务器 (
https://localhost) 。如果这是已部署到本地 IIS Web 服务器的第一个外接程序项目，则系统可能会提示你将 Self-Signed 证书安装到当前用户的“受信任的根证书”存储区。 若要使 IIS Express 正确显示加载项内容，这是必需的操作。
注意
如果 Office 使用 Edge 旧版 Webview 控件 (EdgeHTML) 在 Windows 计算机上运行外接程序，Visual Studio 可能会提示你添加本地网络环回豁免。 这是 Webview 控件能够访问部署到本地 IIS Web 服务器的网站所必需的。 还可以在 Visual Studio 中的“工具”>“选项”>“Office 工具(Web)”>“Web 加载项调试”下随时更改此设置。 若要了解在 Windows 计算机上使用了哪些 Webview 控件，请参阅 Office 外接程序使用的浏览器和 Webview 控件。
接下来，Visual Studio 会执行以下操作：
修改复制到目录) 的仅外接程序清单文件 (
_ProjectName_\bin\Debug\OfficeAppManifests的 SourceLocation 元素，方法是将令牌替换为~remoteAppUrl起始页的完全限定地址 (例如https://localhost:44302/Home.html) 。在 IIS Express 中启动 Web 应用程序项目。
验证清单。
重要
如果清单出现验证错误，则可能是 Visual Studio 的清单架构文件尚未更新以支持最新功能。 第一个故障排除步骤应是将其中一个或多个文件替换为最新版本。 有关详细说明，请参阅 Visual Studio 项目中的清单架构验证错误。
打开 Office 应用程序并旁加载加载项。
调试加载项
在 Visual Studio 2022 中调试加载项的最佳方法取决于加载项是在 WebView2 中运行的，WebView2 是与 Microsoft Edge (Chromium) 关联的 Webview 控件，还是旧版 Web 视图控件。 若要确定正在使用哪个 Webview 控件，请参阅 Office 外接程序使用的浏览器和 Web 视图控件。如果计算机使用 WebView2，请参阅 使用内置的 Visual Studio 调试器在桌面上进行调试。 对于任何其他 Web 视图控件，请参阅 使用浏览器开发人员工具在桌面上进行调试。
使用内置的 Visual Studio 调试器在桌面上进行调试
根据需要，在源 JavaScript 或 TypeScript 文件中设置断点。 可以在启动外接程序之前或之后执行此操作，如前面的启动 外接程序项目部分中所述。 如果设置断点导致 Internet Information Services (IIS) 服务器关闭，请在设置断点后重启调试。
加载项运行时，使用外接程序的 UI 运行包含断点的代码。
重要
在 中 Office.initialize 设置或 Office.onReady 未命中断点。 若要调试这些方法，请参阅 调试 initialize 和 onReady 函数。
提示
如果遇到任何问题，请参阅 在 Visual Studio 中调试 JavaScript 或 TypeScript 应用了解详细信息。
使用浏览器开发人员工具在桌面上进行调试
按照前面部分 启动外接程序项目中的步骤操作。
在 Office 应用程序中启动加载项（如果尚未打开）。 例如，如果它是任务窗格加载项，则会将按钮添加到 “主页” 功能区 (例如“ 显示任务窗格 ”按钮) 。 选择功能区上的按钮。
注意
如果 Visual Studio 未旁加载加载项，则可以手动旁加载它。 按照说明旁 加载 Office 加载项以 测试平台。
在可用外接程序列表中，找到“开发人员外接程序”部分并选择你的外接程序进行注册。
提示
任务窗格在首次打开时可能显示为空白。 如果是这样，则应在后面的步骤中启动调试工具时正确呈现。
打开 “个性”菜单 ，然后选择“ 附加调试器”。 此操作将打开 Office 用于在 Windows 计算机上运行加载项的 Webview 控件的调试工具。 可以按以下文章之一所述设置断点并逐步执行代码：
若要对代码进行更改，请先停止 Visual Studio 中的调试会话并关闭 Office 应用程序。 进行更改，并启动新的调试会话。
在 web Microsoft 365 中调试加载项项目
本部分介绍如何在 Web 桌面 Office 中启动和调试加载项;即加载项项目的 “启动操作” 属性设置为 Microsoft Edge 时。
在 Web 上启动外接程序项目
通过从菜单栏中选择“ 调试>开始调试” 或按 F5 按钮启动项目。 Visual Studio 会自动生成解决方案并启动 Microsoft 365 租户的 Office 应用程序主机页。
注意
在 Web 上调试加载项时，可能会收到类似于以下内容的AADSTS50011错误：
“请求中指定的重定向 URI {Full absolute URL to add-in home page} 与为应用程序配置的重定向 URI 不匹配..."
这是因为部署到 SharePoint 的新 Web 应用程序可能需要长达 24 小时才能可用。 若要使加载项立即可调试，请执行以下步骤：
在 Visual Studio 中停止调试。
使用以下行创建 PowerShell 脚本 。 将占位符
{Full absolute URL to add-in home page}替换为错误消息中的重定向 URL，例如“https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx"”。Connect-MgGraph -Scopes Application.ReadWrite.All $sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'" $sharepointPrincipal | fl $replyUrls = $sharepointPrincipal.ReplyUrls $replyUrls += "{Full absolute URL to add-in home page}" Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls在 PowerShell 中运行脚本。
通过从菜单栏中选择“ 调试>”“开始调试 ”或按 F5 按钮来重启项目。
当 Visual Studio 生成项目时，它会执行以下任务。
提示输入登录凭据。 如果系统要求你重复登录，或者收到错误，指出你未授权，则可能会对 Microsoft 365 租户上的帐户禁用基本身份验证。 在这种情况下，请尝试使用 Microsoft 帐户。 还可以尝试在外接程序项目属性窗格中将 “使用多重身份验证 ”属性设置为 True 。 请参阅 外接程序项目属性。
创建仅外接程序清单文件的副本，并将其添加到目录中
_ProjectName_\bin\Debug\OfficeAppManifests。 Microsoft 365 在启动 Visual Studio 并调试加载项时使用此副本。生成 Web 应用程序项目，然后将其部署到 Microsoft 365 租户。
接下来，Visual Studio 会执行以下操作：
修改复制到目录) 的仅外接程序清单文件 (
_ProjectName_\bin\Debug\OfficeAppManifests的 SourceLocation 元素，方法是将令牌替换为~remoteAppUrl起始页的完全限定地址 (例如https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx) 。启动 Web 应用程序项目。
验证清单。
重要
如果清单出现验证错误，则可能是 Visual Studio 的清单架构文件尚未更新以支持最新功能。 第一个故障排除步骤应是将其中一个或多个文件替换为最新版本。 有关详细说明，请参阅 Visual Studio 项目中的清单架构验证错误。
在 Microsoft Edge 中打开 Microsoft 365 租户的 Office 应用程序主机页。
在 Web 上调试加载项
在 Visual Studio 2022 中调试加载项的最佳方法取决于加载项是在 WebView2 中运行的，WebView2 是与 Microsoft Edge (Chromium) 关联的 Webview 控件，还是旧版 Web 视图控件。 若要确定正在使用哪个 Webview 控件，请参阅 Office 外接程序使用的浏览器和 Web 视图控件。如果计算机使用 WebView2，请参阅 使用内置的 Visual Studio 调试器在 Web 上进行调试。 有关任何其他 Web 视图控件，请参阅 使用浏览器开发人员工具在 Web 上进行调试。
使用内置的 Visual Studio 调试器在 Web 上进行调试
根据需要，在源 JavaScript 或 TypeScript 文件中设置断点。 可以在启动加载项之前或之后执行此操作，如前面部分在 Web 上启动外接程序项目中所述。
加载项运行时，使用外接程序的 UI 运行包含断点的代码。
提示
- 有时在 Outlook 网页版中，Visual Studio 调试器不会附加。 如果出现指示不会命中的断点的错误，请使用浏览器开发人员工具附加到 Visual Studio 调试器：按 F5 开始调试且打开 Outlook 网页版后，请按照 使用浏览器开发人员工具在 Web 上进行调试中的前四个步骤操作。 (使用基于 Chromium 的 Microsoft Edge () .) 的说明 在浏览器工具中设置断点并命中该断点后，浏览器工具和 VisualStudio 中的执行将暂停在断点上。 这表示已附加 Visual Studio 调试器。 此时，可以像平常一样关闭浏览器工具并在 Visual Studio 中添加断点。
- 如果遇到任何问题，请参阅 在 Visual Studio 中调试 JavaScript 或 TypeScript 应用了解详细信息。
使用浏览器开发人员工具在 Web 上进行调试
对于除 Outlook 之外的任何主机中的加载项，请在 Office 主机应用程序页中按 F12 打开调试工具。
对于 Outlook 加载项，如果加载项的清单配置为阅读图面，请选择电子邮件或约会项目，以在其自己的窗口中打开它。 如果仅针对撰写图面配置了加载项，请打开新邮件、答复邮件或新约会窗口。 确保相应的窗口具有焦点，然后按 F12 以笔触调试工具。
打开该工具后，启动加载项。 具体步骤因外接程序的设计而异。 通常，按按钮打开任务窗格。 在 Outlook 中，在窗口顶部的工具栏中，选择“ 更多应用 ”按钮，然后从打开的标注中选择加载项。
使用以下文章之一中的说明设置断点并逐步执行代码。 每个指南都有一个指向更详细指南的链接。
提示
若要调试在
Office.initialize函数中运行的代码或Office.onReady外接程序打开时运行的函数，请设置断点，然后关闭并重新打开加载项。 有关这些函数的详细信息，请参阅 初始化 Office 外接程序。若要更改代码，请先在 Visual Studio 中停止调试会话并关闭 Outlook 页面。 进行更改，并启动新的调试会话。
使用现有文档调试外接程序
如果你有一个文档包含要在调试 Excel、PowerPoint 或 Word 外接程序时使用的测试数据，则可以将 Visual Studio 配置为在启动项目时打开该文档。 若要指定在调试外接程序时要使用的现有文档，请完成以下步骤。
在“解决方案资源管理器”中，选择外接程序项目（而不是 Web 应用程序项目）。
从菜单栏中，选择“项目”>“添加现有项”。
在“添加现有项”对话框中，找到并选择要添加的文档。
选择“添加”按钮以将文档添加到项目中。
在“解决方案资源管理器”中，选择外接程序项目（而不是 Web 应用程序项目）。
在菜单栏中，依次选择“视图”>“属性窗口”。
在“属性”窗口中，选择“启动文档”列表，然后选择添加到项目中的文档。 该项目现在配置为在该文档中启动外接程序。
后续步骤
在外接程序正常工作后，请参阅部署和发布 Office 外接程序，以了解可用于将外接程序分发给用户的方法。