SharePoint 加载项模型中的事件接收器和列表事件接收器

在新 SharePoint 外接程序模型中处理 SharePoint 中的事件的方法与使用完全信任代码不同。

在典型的完全信任代码 (FTC)/场解决方案中，使用 SharePoint 创建事件接收器和列表事件收件人

服务器端对象模型代码通过解决方案进行部署。 在这种情况下，事件接收器代码在 SharePoint 服务器上运行。

在 SharePoint 外接程序模型方案中，事件接收器在 Web 服务内部的 SharePoint 外部创建，并使用 SharePoint 注册。 这些事件接收器称为远程事件接收器 (RER)。 在这一方案下，事件接收器代码在托管 Web 服务的 Web 服务器上运行。

重要

自 2017 年 1 月起，SharePoint Online 支持列表 Webhook，可用于取代过去的远程事件接收器。 若要详细了解 Webhook，请参阅 SharePoint Webhook 概述。 另请注意，还可以从 sp-dev-samples GitHub 存储库中获取多个 Webhook 示例。

高级别准则

作为经验法则，我们希望提供下列创建事件接收器的高级别准则。

• 实现事件接收器的服务终结点必须可被匿名用户访问。
• 添加到外接程序 Web 的事件接收器允许你返回访问令牌。
• 如果事件接收器是从使用应用访问令牌的应用上下文应用的且主机 Web 中的操作（ItemAdded 等）是由最终用户驱动的，则添加到主机 Web 的事件接收器将返回访问令牌。
• AppInstalled 事件必须在 30 秒内完成，否则 SharePoint 将认为它已经失败。 SharePoint 将返回该事件 3 次并在第四次执行 SharePoint 之后将认为外接程序安装失败
• 常规事件（如 ItemAdded）还具有 30 秒的超时，但没有重试机制
• 添加到没有应用上下文的主机 Web 的事件接收器，例如使用 SharePointOnlineCredentials 或其他方式，将不会返回访问令牌，而且你必须使用仅限应用的访问令牌访问主机 Web
• 支持将事件接收器添加到主机 Web。
  • 只有通过 CSOM/REST API 才能实现此操作，不能使用 Visual Studio 向导。
• SharePoint 一定会调用针对每个给定的事件配置的事件接收器终结点。 但是，不能保证事件接收器终结点中的代码将执行，因为该代码未在 SharePoint 服务器上运行。

例如：

如果事件接收器终结点 URL 不可用，则事件接收器代码将不执行。 URL 可能由于多种原因而不可用。 一些最常见的原因包括注册终结点 URL 时配置错误、尝试解析 URL 时出现 DNS 问题，或者托管终结点的网站已关闭或处于不可操作状态。

此外，如果编写不当的事件接收器代码中存在 bug，则无法通知 SharePoint 出现 bug，应再次执行该事件。 可以通过附加到 SharePoint 列表的事件接收器在一定程度上解决此问题。 有关此方法的详细信息，请参阅下文。

• 事件接收器执行大量的代码时应使用异步模式。
• 有关事件接收器中超时的详细信息，请参阅下面的 MSDN 文章。 (在文章中搜索超时。) 处理 SharePoint 外接程序中的事件 (MSDN 文章)
• 当事件接收器对 SharePoint 列表进行操作时，我们建议使用特定的更改跟踪机制与事件接收器一起确保高质量处理。
  • 有关此模式以及如何实现此模式的详细信息，请参阅下面的 O365 PnP 代码示例。 Core.ListItemChangeMonitor（O365 PnP 示例）

调试事件接收器

若要调试事件接收器，需要在 Azure 和 Visual Studio 中配置一些不同的内容。 以下文章提供了分步说明以及与调试相关的详细信息。

• 在 SharePoint 外接程序中调试远程事件接收器并排除故障（MSDN 博客文章）

更多示例

• Core.EventReceivers（O365 PnP 示例）
  • 此示例演示了 SharePoint 外接程序如何使用”已安装应用”事件在主机 Web 中执行额外工作，如将事件接收器连接到主机 Web 中的列表。
• Core.AppEvents.HandlerDelegation（O365 PnP 示例）
  • 此示例演示如何在以下情况下实现 AppInstalled 和 AppUninstalling 事件的处理程序：
    1. 处理程序遇到错误时包含回滚逻辑。
    2. 失败或用时超过 30 秒才完成时包含“已完成”逻辑以接受 SharePoint 重试处理程序超过三次的事实。
    3. 使用处理程序委托战略尽量减少从处理程序 Web 服务对 SharePoint 的调用。
    4. 使用 CSOM 类 ExceptionHandlingScope 和 ConditionalScope。
• Core.AppEvents（O365 PnP 示例）
  • 此示例演示如何在以下情况下实现 AppInstalled 和 AppUninstalling 事件的处理程序：
    1. 处理程序遇到错误时包含回滚逻辑。
    2. 失败或用时超过 30 秒才完成时包含“已完成”逻辑以接受 SharePoint 重试处理程序超过三次的事实。

相关链接

• SharePoint 2013 中的远程事件接收器常见问题解答（MSDN 文章）
• 在 SharePoint 外接程序中创建远程事件接收器（MSDN 文章）
• 在 SharePoint 2013 中创建应用事件接收器（MSDN 文章）
• 指南文章中 https://aka.ms/OfficeDevPnPGuidance
• MSDN 中的引用位于 https://aka.ms/OfficeDevPnPMSDN
• 视频中的 https://aka.ms/OfficeDevPnPVideos

PnP 示例

• Core.ListItemChangeMonitor（O365 PnP 示例）
• Core.EventReceivers（O365 PnP 示例）
• Core.AppEvents.HandlerDelegation（O365 PnP 示例）
• Core.AppEvents（O365 PnP 示例）
• 示例和内容（网址为 https://github.com/SharePoint/PnP）

适用于

• Office 365 多租户 (MT)
• Office 365 专用 (D)
• SharePoint 2013 本地