Outlook 上下文加载项激活故障排查

Outlook 上下文加载项激活基于加载项 XML 清单中的激活规则。 当当前选定项的条件满足加载项的激活规则时，应用程序会在 Outlook UI (加载项选择窗格中激活并显示加载项按钮，用于撰写加载项，加载项栏用于读取加载项) 。 但是，如果你的外接程序未按预期激活，则应调查以下方面，确定可能的原因。

重要

基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。 停用此功能的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。 以下 API 也将停用。

• Office.context.mailbox.item.getEntities ()
• Office.context.mailbox.item.getEntitiesByType (entityType)
• Office.context.mailbox.item.getFilteredEntitiesByName (名称)
• Office.context.mailbox.item.getSelectedEntities ()

为了帮助最大程度地减少潜在的中断，在基于实体的上下文加载项停用后，仍支持以下内容。

• 正在开发由联机会议加载项激活的 “加入 会议”按钮的替代实现。 结束对基于实体的上下文加载项的支持后，联机会议加载项将自动转换为替代实现，以激活“ 加入会议 ”按钮。
• 基于实体的上下文加载项停用后，将继续支持正则表达式规则。 建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。 有关如何实现这些规则的指南，请参阅 使用正则表达式激活规则显示 Outlook 加载项。

有关详细信息，请参阅 基于实体的上下文 Outlook 加载项的停用。

用户邮箱是否位于至少为 Exchange 2016 的 Exchange Server 版本上？

首先，确保用于测试的用户的电子邮件帐户位于至少为 Exchange 2016 的 Exchange Server 版本上。 如果使用 Exchange 2016 之后发布的特定功能，请确保用户帐户位于相应 Exchange 版本上。

可以使用以下方法之一来验证 Exchange 的版本。

• 咨询你的 Exchange Server 管理员。

• 如果要在Outlook 网页版或移动设备上测试加载项，例如，在脚本调试器 (Internet Explorer) 附带的 JScript 调试器中，查找脚本标记的 src 属性，该属性指定从中加载脚本的位置。 路径应包含子字符串 owa/15.0.516.x/owa2/...，其中 15.0.516.x 表示Exchange Server的版本，例如 15.0.516.2。

• 或者，可使用 Office.context.mailbox.diagnostics.hostVersion 属性来验证版本。 在 Outlook 网页版、移动设备和新的 Outlook on Windows (预览版) 中，此属性返回Exchange Server的版本。

• 如果可以在 Outlook 上测试加载项，则可以使用以下使用 Outlook 对象模型和 Visual Basic 编辑器的简单调试技术。

  1. 首先，验证已对 Outlook 启用了宏。 依次选择“文件”、“选项”、“信任中心”、“信任中心设置”、“宏设置”。 确保在信任中心中选择了“为所有宏提供通知”。 还应在 Outlook 启动过程中选择了“启用宏”。

  2. 在功能区的“开发人员”选项卡上，选择“Visual Basic”。

     注意

     看不到“开发工具”选项卡？ 请参阅如何：在功能区上显示“开发工具”选项卡将其打开。

  3. 在 Visual Basic 编辑器中，依次选择“视图”和“即时窗口”。

  4. 在即时窗口中键入以下内容以显示 Exchange Server 的版本。 返回值的主版本必须等于或大于 15。

     • 如果用户的配置文件中只有一个 Exchange 帐户：

      ?Session.ExchangeMailboxServerVersion
     

     • 如果同一用户配置文件中有多个 Exchange 帐户（emailAddress 表示包含用户主 SMTP 地址的字符串）：

      ?Session.Accounts.Item(emailAddress).ExchangeMailboxServerVersion
     

加载项是否可用？

Windows 和 Mac 上的 Outlook 可能会由于性能原因而使加载项不可用，包括超出 CPU 核心或内存的使用阈值、崩溃容忍度以及处理加载项的所有正则表达式的时间长度。 发生这种情况时，Windows 和 Mac 上的 Outlook 会显示一条通知，指出加载项不可用。

注意

仅经典 Outlook on Windows 和 Outlook on Mac 监视资源使用情况。 但是，在经典 Outlook on Windows 或 Outlook on Mac 中不可用的加载项在 Outlook 网页版、移动设备和新的 Outlook on Windows (预览版) 中也变得不可用。

检查已安装的加载项列表，验证加载项是否可用。 有关如何在 Outlook 中查看加载项的说明，请参阅 在 Outlook 中使用外接程序。

已测试项是否支持 Outlook 外接程序？ 所选项目是否由至少为 Exchange 2016 的 Exchange Server 版本交付？

如果你的 Outlook 加载项为阅读加载项，并且应该在用户查看消息（包括电子邮件、会议请求、响应和取消）或约会时激活，尽管这些项目通常支持加载项，但还是存在例外情况。 检查所选项目是否为 Outlook 加载项未激活的其中一项。

此外，由于约会始终以 RTF 格式保存，因此指定 BodyAsHTML的 PropertyName 值的 ItemHasRegularExpressionMatch 规则不会在以纯文本或 RTF 格式保存的约会或邮件上激活加载项。

即使邮件项目不是上述类型之一，如果该邮件不是由至少为 Exchange 2016 的 Exchange Server 版本传递的，则不会在该邮件上标识已知的实体和属性（如发件人的 SMTP 地址）。 不会满足依赖于这些实体或属性的任何激活规则，并且不会激活加载项。

加载项清单是否安装正确，Outlook 是否有已缓存副本？

注意

当外接程序使用 Microsoft 365 的统一清单时，不支持依赖于激活规则的 Outlook 外接程序功能。

此方案仅适用于 Windows 版 Outlook。 正常情况下，为邮箱安装 Outlook 外接程序时，Exchange Server 会将外接程序清单从你指示的位置复制到该 Exchange Server 上的邮箱。 每次 Outlook 启动时，它都会将针对该邮箱安装的所有清单读入以下位置的临时缓存中。

%LocalAppData%\Microsoft\Office\16.0\WEF

例如，对于用户 John，缓存可能位于 C：\Users\john\AppData\Local\Microsoft\Office\16.0\WEF。

如果加载项未为任何项目激活，则清单可能未正确安装在Exchange Server上，或者 Outlook 在启动时未正确读取清单。 使用 Exchange 管理中心确保已为您的邮箱安装和启用外接程序，并在必要时重新启动 Exchange Server。

下图显示了验证 Outlook 是否具有有效版本的清单的步骤摘要。

以下过程描述详细信息。

1. 如果在 Outlook 打开时修改了清单，并且未使用 Visual Studio 2015 或更高版本的 Visual Studio 开发加载项，则应卸载加载项并使用 Exchange 管理员中心重新安装它。

2. 重新启动 Outlook 并测试 Outlook 现在是否已激活加载项。

3. 如果 Outlook 无法激活外接程序，则检查 Outlook 是否具有外接程序清单的正确缓存副本。 在以下路径下查看。

   %LocalAppData%\Microsoft\Office\16.0\WEF
   

   可以在以下子文件夹中找到清单。

   \<insert your guid>\<insert base 64 hash>\Manifests\<ManifestID>_<ManifestVersion>
   

   注意

   下面是为用户 John 安装的邮箱的清单的路径示例。

   C:\Users\john\appdata\Local\Microsoft\Office\16.0\WEF\{8D8445A4-80E4-4D6B-B7AC-D4E6AF594E73}\GoRshCWa7vW8+jhKmyiDhA==\Manifests\b3d7d9d5-6f57-437d-9830-94e2aaccef16_1.2
   

   验证要测试的加载项的清单是否在已缓存清单中。

4. 如果清单在缓存中，请跳过本节的其余部分，并考虑本节后面的其他可能原因。

5. 如果清单不在缓存中，请检查 Outlook 是否已确实从 Exchange Server 中成功读取清单。 为此，请使用 Windows 事件查看器：

   1. 在“Windows 日志”下，选择“应用程序”。

   2. 查找其事件 ID 等于 63（表示 Outlook 从 Exchange Server 下载清单）的近期事件。

   3. 如果 Outlook 成功读取清单，则记录的事件应具有以下说明。

      The Exchange web service request GetAppManifests succeeded.
      

      然后，跳过本节的其余部分，并考虑本节后面的其他可能原因。

6. 如果未看到成功的事件，请关闭 Outlook 并删除以下路径中的所有清单。

   %LocalAppData%\Microsoft\Office\16.0\WEF\<insert your guid>\<insert base 64 hash>\Manifests\
   

   启动 Outlook，并测试 Outlook 现在是否已激活加载项。

7. 如果 Outlook 无法激活加载项，请返回到第 3 步，再次确认 Outlook 是否已正确读取清单。

加载项清单有效吗？

请参阅验证并排查清单问题来调试加载项清单问题。

使用的激活规则是否合适？

从 Office 外接程序清单架构版本 1.1 开始，可以创建当用户处于撰写表单 (撰写加载项) 或阅读窗体 (读取加载项) 时激活的加载项。 确保为外接程序将在其中激活的每种窗体类型指定相应的激活规则。 例如，可以将 FormType 属性设置为 Edit 或 ReadOrEdit 的 ItemIs 规则激活撰写外接程序，并且不能使用任何其他类型的规则，例如 ItemHasKnownEntity 和 ItemHasRegularExpressionMatch 规则来撰写外接程序。有关详细信息，请参阅 Outlook 加载项的激活规则。

如果使用正则表达式，该表达式的指定是否正确？

由于激活规则中的正则表达式是阅读加载项的 XML 清单文件的一部分，因此当正则表达式使用特定字符时，请务必遵守 XML 处理器支持的相应转义序列。 下表列出了这些特殊字符。

字符	说明	要使用的转义序列
"	双引号	"
&	与号	&
'	撇号	'
<	小于号	<
>	大于号	>

如果使用正则表达式，阅读加载项是否会在Outlook 网页版、移动设备或 Windows () 预览版中激活，但不在经典 Outlook on Windows 或 Outlook on Mac 中激活？

经典 Outlook on Windows 和 Outlook on Mac 使用正则表达式引擎，该引擎不同于 Outlook 网页版 使用的正则表达式引擎，在移动设备上，以及新 Outlook on Windows (预览版) 。 经典 Outlook on Windows 和 Outlook on Mac 使用作为 Visual Studio 标准模板库的一部分提供的 C++ 正则表达式引擎。 该引擎符合 ECMAScript 5 标准。 Outlook 网页版、移动设备和新的 Outlook on Windows (预览版) 使用作为 JavaScript 的一部分的正则表达式计算，它由浏览器提供，并支持 ECMAScript 5 的超集。

虽然在大多数情况下，这些 Outlook 客户端在激活规则中发现相同正则表达式的相同匹配项，但也有例外。 例如，如果正则表达式包含基于预定义字符类的自定义字符类，则经典 Outlook on Windows 和 Outlook on Mac 可能会返回不同于Outlook 网页版、移动设备和新的 Windows 版 Outlook (预览版) 的结果。 例如，包含速记字符类的字符类 [\d\w] 将返回不同的结果。 在这种情况下，若要避免不同应用程序出现不同的结果，请改用 (\d|\w) 。

全面测试正则表达式。 如果它返回不同的结果，请重新编写该正则表达式，以便同时与两个引擎相兼容。 若要在经典 Outlook on Windows 和 Outlook on Mac 中验证评估结果，请编写一个小型 C++ 程序，该程序对尝试匹配的文本示例应用正则表达式。 在 Visual Studio 上运行的 C++ 测试程序将使用标准模板库，在运行同一正则表达式时模拟经典 Outlook on Windows 或 Outlook on Mac 的行为。 若要在 Outlook 网页版、移动设备和新的 Windows 版 Outlook (预览版) 中验证评估结果，请使用你最喜欢的 JavaScript 正则表达式测试器。

如果使用 ItemIs、ItemHasAttachment 或 ItemHasRegularExpressionMatch 规则，是否已验证相关项属性？

如果使用 ItemHasRegularExpressionMatch 激活规则，请验证 PropertyName 属性的值是否为选定项的预期值。 下面是调试相应属性的一些提示。

• 如果选定项是邮件，并且你在 PropertyName 属性中指定 BodyAsHTML，请打开该邮件，然后选择“查看源代码”验证该项的 HTML 形式的邮件正文。

• 如果选定项是约会，或者激活规则在 PropertyName 中指定 BodyAsPlaintext，则可使用 Outlook 对象模型和 Windows 版 Outlook 中的 Visual Basic 编辑器：

  1. 确保已启用宏，并且 Outlook 的功能区上显示了“ 开发工具 ”选项卡。

  2. 在 Visual Basic 编辑器中，依次选择“视图”和“即时窗口”。

  3. 键入以下内容显示与具体应用场景相关的各个属性。

     • 在 Outlook 资源管理器中选择的邮件或约会项的 HTML 正文：

     ?ActiveExplorer.Selection.Item(1).HTMLBody
     

     • 在 Outlook 资源管理器中选择的邮件或约会项的纯文本正文：

     ?ActiveExplorer.Selection.Item(1).Body
     

     • 在当前的 Outlook 检查器中打开的邮件或约会项的 HTML 正文：

     ?ActiveInspector.CurrentItem.HTMLBody
     

     • 在当前的 Outlook 检查器中打开的邮件或约会项的纯文本正文：

     ?ActiveInspector.CurrentItem.Body
     

如果 ItemHasRegularExpressionMatch 激活规则指定 Subject 或 SenderSMTPAddress，或者如果使用 ItemIs 或 ItemHasAttachment 规则，并且熟悉或想要使用 MAPI，请使用 MFCMAPI。 在下表中验证规则所依赖的 MAPI 属性。

规则类型	验证此 MAPI 属性
使用 Subject 的 ItemHasRegularExpressionMatch 规则	PidTagSubject
使用 SenderSMTPAddress 的 ItemHasRegularExpressionMatch 规则	PidTagSenderSmtpAddress 和 PidTagSentRepresentingSmtpAddress
ItemIs	PidTagMessageClass
ItemHasAttachment	PidTagHasAttachments

验证属性值后，即可使用正则表达式评估工具来测试正则表达式是否在该值中找到匹配项。

Outlook 是否按预期将所有正则表达式应用于项目正文部分？

本部分适用于所有使用正则表达式的激活规则，尤其是那些应用于项正文的激活规则，这些规则可能很大，需要更长的时间才能计算匹配项。 应注意，即使激活规则所依赖的项属性具有预期值，Outlook 也可能无法针对项目属性的整个值计算所有正则表达式。 为了提供合理的性能并控制读取加载项过度的资源使用，Outlook 在运行时处理激活规则中的正则表达式时遵循以下限制。

• 计算的项目正文的大小。 Outlook 计算正则表达式所基于的项目正文部分存在限制。 这些限制取决于 Outlook 客户端、外形规格和项目正文的格式。 有关详细信息，请参阅 评估的项目正文的大小限制。

• 正则表达式匹配的数目。 Windows 版 Outlook (经典版和 新的 (预览版) ) 、Mac 版、Web 版和移动设备上，每个版本最多返回 50 个正则表达式匹配项。 这些匹配项是唯一的，重复匹配项不计入此限制。 不要假定返回的匹配项的任何顺序，也不要假定经典 Outlook on Windows 和 Outlook on Mac 中的顺序与 Outlook 网页版、移动设备和 Windows (预览版新 Outlook) 中的顺序相同。 如果你希望你的激活规则中存在正则表达式的许多匹配项，而你缺少某个匹配项，则表示你可能超出此限制。

• 正则表达式匹配的长度。 Outlook 应用程序将返回的正则表达式匹配项的长度存在限制。 Outlook 不包含超出限制的任何匹配项，也不会显示任何警告消息。 你可以使用其他正则表达式评估工具或独立的 C++ 测试程序运行你的正则表达式，以验证你是否具有超出此类限制的匹配项。 下表汇总了限制。 有关详细信息，请参阅 上下文 Outlook 外接程序的激活规则限制。

  正则表达式匹配项的长度限制	Outlook 网页版、移动设备和新的 Windows 客户端 (预览)	经典 Windows 客户端和 Mac 上的 Outlook
  项目正文采用纯文本	3KB	1.5 KB
  项目正文采用 HTML	3 KB	3KB

• 用于评估经典 Outlook on Windows 和 Outlook on Mac 中读取加载项的所有正则表达式所花费的时间。 默认情况下，对于每个读取加载项，Outlook 必须在一秒内完成其激活规则中的所有正则表达式的评估。 否则，Outlook 最多重试三次，如果 Outlook 无法完成评估，则加载项不可用。 Outlook 在通知栏中显示一条消息，指出加载项不可用。 正则表达式可用的时间可通过设置组策略或注册表项来进行修改。

  注意

  如果经典 Outlook on Windows 或 Mac 版 Outlook 使读取加载项不可用，则读取加载项在 Outlook 网页版、移动设备和 Windows (预览版) 中的同一邮箱上变得不可用。

另请参阅

• 部署和安装 Outlook 加载项以进行测试
• Outlook 加载项的激活规则
• 使用正则表达式激活规则显示 Outlook 加载项
• Outlook 外接程序的激活和 JavaScript API 限制
• 验证并排查清单问题