SharePoint Add-in Model: Understanding Event Receivers and List Event Receivers

The MSDN article suggests employing a distinct alteration tracking mechanism to complement event receivers for superior processing of SharePoint list events. Despite obtaining an OAuth token with full SharePoint online permissions, the individual was unable to retrieve events through the POST call mentioned above after attaching event receivers.

The method of managing events in SharePoint has undergone a change in the new
SharePoint Add
-in model compared to Full Trust Code.

In a common situation involving Full Trust Code (FTC) or Farm Solution, SharePoint users usually generate
event receivers
and List
Event Receivers
.

The code for
event receiver
is executed on the SharePoint server and is implemented through Solutions that utilize the Server Side Object Model.

When using the SharePoint Add-in model, event receivers are generated in a web service outside of SharePoint and then registered with it. Such receivers are referred to as Remote Event Receivers (RER), and their code is executed on the web server where the service is located.

Important

Starting from January 2017,
SharePoint Online
now offers the option of using list webhooks, which can be used in place of the previously used “-ed”
Remote event receivers
. To gain a better understanding of webhooks, refer to the Overview of SharePoint webhooks. Additionally, it is worth noting that numerous webhook examples can be found on the sp-dev-samples GitHub repository.

High-level guidelines

We aim to offer some general principles for developing event receivers as a guiding principle.

  • For the event receiver to be implemented, the service end point should be accessible to all users without the need for authentication.
  • By adding event receivers to the Add-in web, it becomes possible to retrieve an access token.
  • If app access token is utilized and the operation in the host web is initiated by the end user (such as ItemAdded), the addition of event receivers to the host web will result in the retrieval of an access token.
  • The AppInstalled event has a time limit of 30 seconds. If it exceeds this limit, SharePoint will assume that it has
    failed. SharePoint
    and will try running the event three more times. If the event still fails after the fourth execution, SharePoint will mark the add-in installation as unsuccessful.
  • Events such as ItemAdded have a 30-second timeout, but lack a retry mechanism.
  • If event receivers are added to a host web without an app context, such as through the use of SharePointOnlineCredentials or other methods, an access token will not be returned. In this case, the host web must be accessed with an app-only access token.
  • The host web allows for the addition of event receivers.
  • SharePoint is known to invoke the event receiver end points that are set up for a particular event. However, it cannot be assured that the code present within these end points will be executed, as the code is not executed on the SharePoint server.

For example:

In case the end point URL of the event receiver is not accessible, the code of the receiver will not run. This can happen due to various reasons, such as inappropriate configuration during registration of the end point URL, difficulty in resolving the URL because of DNS issues, or unavailability of the website hosting the end point due to shutdown or inoperability.

In case of a bug in badly written event receiver code, it is impossible to inform SharePoint about the bug and request the event to execute again. One potential solution is to use event receivers that are linked to SharePoint lists. Further details about this method are discussed below.

  • If a considerable amount of code is executed by an event receiver, it is advisable to implement an asynchronous pattern.
  • To learn more about timeouts in event receivers, refer to the MSDN article on handling events in add-ins for SharePoint. Simply search for “timeout” within the article.
  • To ensure better processing of SharePoint lists with event receivers, it is advised to utilize a dedicated change tracking mechanism in conjunction with the receiver.

Debugging Event Receivers

In order to troubleshoot event receivers, certain configurations must be made in both Azure and Visual Studio. A comprehensive guide with detailed instructions and additional debugging information can be found in the article below.

  • Resolve issues and trace errors in a
    remote event receiver
    within a SharePoint add-in (as mentioned in an MSDN blog post).

More Examples

  • This sample from O365 PnP, called Core.EventReceivers, is accompanied by the MSDT_li1 hashtag.
  • The O365 PnP Sample, Core.AppEvents.HandlerDelegation, includes four items listed as
  • This sample shows how to implement handlers for the AppInstalled and AppUninstalling events that:

    1. Incorporate rollback logic if the handler encounters an error.
    2. ,

    3. Incorporate “already done” logic to accommodate the fact that SharePoint retries the handler up to three more times if it fails or takes more than 30 seconds to complete.

    4. ,

    5. Use the handler delegation strategy to minimize calls from the handler web service to SharePoint.
    6. , and

    7. Use the CSOM classes ExceptionHandlingScope and ConditionalScope.
    8. .

  • The O365 PnP Sample, Core.AppEvents, includes the following elements:
    – MSDT_li1
    – MSDT_li2

Related links

  • Frequently Asked Questions (FAQ) for
    Event Receivers in SharePoint 2013
    that can be accessed remotely (MSDN article).
  • Incorporate a SharePoint add-in to establish a recipient for
    Remote Event
    (MSDN documentation).
  • Develop an event receiver for an application in
    SharePoint 2013
    as explained in the MSDN article.
  • You can find articles with guidance on Office Development and SharePoint at https://aka.ms/OfficeDevPnPGuidance.
  • The MSDN contains useful references that can be accessed through the link https://aka.ms/OfficeDevPnPMSDN.
  • Access the OfficeDevPnPVideos by visiting https://aka.ms/OfficeDevPnPVideos.

PnP samples

  • The O365 PnP Sample includes a class called Core.ListItemChangeMonitor.
  • This O365 PnP sample is related to the Core.EventReceivers.
  • This is a sample of O365 PnP that showcases the delegation of Handler to Core.AppEvents.
  • Core.AppEvents (O365 PnP Sample)
  • You can find both examples and materials on https://github.com/SharePoint/PnP.

Applies to

  • Office 365 Multi Tenant (MT)
  • Office 365 Dedicated (D)
  • SharePoint 2013 on-premises

Frequently Asked Questions

Posted in Uncategorized