Remote Event Receivers in SharePoint 2013

In SharePoint 2010, event receivers handle events that occur on SharePoint lists, sites, and other SharePoint objects by running the code on the SharePoint server (either full-trust or in a sandbox). This type of event receiver still exists in SharePoint 2013. However, SharePoint 2013 also supports remote event receivers in which the code that runs when the event is triggered is hosted by a web service. This means that if you register a remote event receiver, you also need to tell SharePoint which web service to invoke. In Table 1, the code example on the left (SharePoint solutions) implements functionality using an event handler. The example on the right (apps for SharePoint) implements the same functionality using a remote event receiver.

 Remote event receivers are very similar to the regular event receivers we know from earlier versions of SharePoint: they are triggered when a certain event happens, we can specify which code has to run for which event and we can choose between synchronous and asynchronous events.

With remote event handlers this will all be the same. The only difference is that the code that will run when the event occurs will be served by a web service. This means that if we register a remote event receiver we will also tell SharePoint which web service needs to run.

How it works

1. The user does an action on SharePoint (e.g. edits a list item).
2. SharePoint talks to ACS  (Access Control Service) and requests a signed token contain information about the current user's context.
3. SharePoint then talks to the registered web service where we can do whatever we want. We could for example update a backend system as a result of the fired event.
4. The backend system sends succes or failure back to the web service.
5. The web service can now also talk to the ACS to request its own signed token to do a call back to SharePoint. So using this token we can do remote actions from within the web service as a result of our earlier operation in the backend system.

If you want to know which events are supported, open up Visual Studio, create a new SharePoint hosted app and add a remote event receiver. In the next screen, as today in Visual Studio 2010, you will see the supported events.

The template code basically has two methods:

1. ProcessEvent: which allows to do the remote call but also provides code to get a context token to do a callback to SharePoint
2. ProcessOneWayEvent: used to do a one way call to the web service without a callback to SharePoint

Registering the remote event receiver

If you look in your app you will see that a new elements file has been added:

<?xml version="1.0" encoding="utf-8"?>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <Receivers ListTemplateId="3100">

      <Receiver>

        <Name>RemoteEventReceiver1ItemAdding</Name>

        <Type>ItemAdding</Type>

        <SequenceNumber>10000</SequenceNumber>

        <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url>

      </Receiver>

  </Receivers>

</Elements>

Using this CAML, we can specify which events we want to support and via the 'Url' tag we can tell SharePoint which web service call needs to be made.

App events

You can also make use of events at the app level. Click on the app project and checkout the properties on the bottom right hand side of the screen. You have settings for 'Handle app installed/uninstalled/upgraded'. When you set these to through, new entries will be added to the app manifest to support these events.

Coding

If you check the generated code, the most important is the default paramater for both methods:

RemoteEventProperties properties

As with regular event handlers, this RemoteEventProperties will give you access to all kinds of details about the incoming event.

Table 1. Code examples for event receivers in SharePoint 2010 vs. remote event receivers in apps

SharePoint solutions

C# // Trigger an event when an item is added to the SharePoint list. Public class OnPlantUpdated : SPItemEventReceiver { Public override void ItemAdding (SPItemEventProperties properties) { Properties.After.Properties.ChangedProperties.Add("Image",CreateLink(properties)); Properties.status =SPEventReceiverStatus.Continue; } /// When an item updates, run the following. Public override void ItemUpdating(SPItemEventProperties properties) { Properties.AfterProperties.ChangedProperties.Add("Image",CreateLink9properties)); Properties.Status= SPEventReceiverStatus.Continue; }

Apps for SharePoint

C# /* Trigger an event when an item is added to the SharePoint list*/ Public class OnPlantUpdated : IRemoteEventService { public SPRemoteEventResult ProcessEvent (SPRemoteEventProperties properties) { SPRemoteEventResult result =new SPRemoteEventResult(); If (properties.EventType == SPRemoteEventType.ItemAdding || properties.EventType == SPRemoteEventType.ItemUpdating) { // Add code that runs when an item is added or updated. }

How do remote event receivers work?

Figure 1 shows how remote event receivers work:

• The user performs an action on SharePoint (for example, edits a list item).
• SharePoint then talks to the registered web service. You could perform some operations—for example, update a list item property, or update a backend system.
• The web service can also talk to the Access Control Service (ACS) to request its own signed token to do a call back to SharePoint. Using this token, you can perform remote actions from within the web service as a result of the earlier operation on the list item or in the backend system.

Figure 1. How remote event receivers work in SharePoint

Can I run client-side (JavaScript) code from remote event receivers?

No.

Are there any restrictions on where a remote event receiver can be hosted or on its URL?

The remote event receiver can be hosted in the cloud or in an on-premise server that is not also being used as a SharePoint server. The URL of a production receiver cannot specify a particular port. This means that you must use either port 443 for HTTPS, which we recommend, or port 80 for HTTP. If you are using HTTPS and the receiver service is hosted on-premise, but the app is on Microsoft SharePoint Online, then the hosting server must have a publically trusted certificate from a certificate authority. (A self-signed certificate works only if the app is in an on-premise SharePoint farm.)

Will a SharePoint 2010 event handler work on SharePoint 2013 after I upgrade?

If a SharePoint 2010 solution package containing an event handler is upgraded to SharePoint 2013, depending on your customizations, the solution package may work without any modifications. This will include the event handler too. If the SharePoint 2010 solution is remodeled into an app for SharePoint in SharePoint 2013, the event handler should be rewritten as a remote event receiver.