SharePoint 2013: remote event receivers

Remote event receivers is another one of the very cool new things we can expect in the upcoming version of SharePoint. 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.