Export (0) Print
Expand All

Remote event receivers FAQ

apps for SharePoint

Get answers to frequently asked questions about using 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. In SharePoint 2013, the code that runs when the event is triggered is served 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.

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

SharePoint solutions

Apps for SharePoint

// 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;
}

/* 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)
{

// Code to run on item adding or updating.
}

See Add list item properties with a remote event receiver for the complete code sample. See Migrating a SharePoint event receiver to a remote event receiver for a detailed demo of the code sample.

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

How remote event receivers work in SharePoint 2013

Remote event receivers are supported at the list and list item level.

Yes. Visual Studio 2012 provides templates to create a remote event receiver. The template creates the "skeleton" for this set up, which you can build on to meet your requirements.

By default, when you use Visual Studio 2012 to create the remote event receiver, there are two methods in the Windows Communication Foundation (WCF) service:

  • ProcessEvent() handles events that occur before an action occurs, such as when a user adds or deletes a list item. This is a synchronous event (two-way that can handle "-ing", or current, events). It can call back to SharePoint (for example, canceling an addition to a list). It is a synchronous event handler.

  • ProcessOneWayEvent() handles events that occur after an action occurs, such as after a user adds an item to a list or deletes an item from a list. This is an asynchronous event (one-way that can handle "-ed", or past, events, and fire and forget type).

The SharePoint 2013 app model introduces a wide range of hosting and developing patterns see Choose patterns for developing and hosting your app for SharePoint for detail information on hosting options. There are three ways you can host apps for SharePoint: provider-hosted, auto-hosted, and SharePoint-hosted. SharePoint-hosted apps do not have a middle-tier/database backend—they are simply client-side JavaScript/HTML apps and therefore do not support remote event receivers. Table 2 summarizes the different hosting models’ support for remote event receivers.

Table 2. Hosting models and remote event receivers

Hosting model

Support for remote event receivers

Auto-hosted

Yes

Provider-hosted

Yes

SharePoint-hosted

No

  • SharePoint-hosted apps can only use the JavaScript client object model (CSOM). In other words, they cannot use server-side code.

  • Remote events in SharePoint require a WCF service to call back when a remote event occurs. In other words, remote events require server-side code.

  • The only way to host a WCF service for SharePoint to call back when a remote event occurs is to host the service in a remote web project. However, the moment you add a remote web project to your project, it becomes an auto-hosted app and is no longer a SharePoint-hosted app.

If you want to handle events, your app must be either an auto-hosted app or a provider-hosted app. Remote events (app events and remote event receivers) are not supported in SharePoint-hosted apps.

The new remote event debugging options are available on the SharePoint tab under the properties page of your app for SharePoint project, as shown in Figure 2.

Figure 2. Configure remote event debugging

Configure remote evenet receiver debugging

All you need to debug remote events is the Service Bus endpoint connection string.

After you enable remote event debugging and configure the Service Bus connection string, you can debug remote events. For more information about debugging, see Update to debugging SharePoint 2013 remote events using Visual Studio 2012.

Note Note

Remote event receiver endpoints don’t have to be deployed as part of apps, they can be deployed separately and referenced by user solutions.

If you have a remote event in your project and have not configured remote event debugging, Visual Studio prompts you to configure remote event debugging (see Figure 3). You can change this behavior by clearing the Notify me if remote event debugging is not configured check box on the SharePoint tab.

Figure 3. Remote event debugging notification

Notifications in remote event receivers

If you forgot to set any of the app-related events in your AppManifest.xml file that handles the code in your remote event receiver WCF service, your debugger might not fire up.

Once the WCF client has successfully hosted all your services, go to the Service Bus namespace in your browser, and you should see your endpoint, as shown in Figure 4.

Figure 4. Browsing to the Service Bus namespace

Browsing to the service bus namespace

Depending on the event, the remote event may be synchronous or asynchronous. It might take a few seconds or more to hit your breakpoint if it is asynchronous.

Events that are "* being *"—such as "item is being added" or "item is being deleted"—are synchronous.

Events that are "* was *"—such as "item was added", "item was deleted"—are asynchronous.

Remote event receivers in an app are registered to the app web only. If you want to register remote event receivers to the host web, you have to register it through the client object model, but your app has to request manage permission to the host web.

You can use app installed events to register your remote event receivers.

  • In Visual Studio, choose your app project in Solution Explorer.

  • In the Properties panel, set the Handle App Installed property to true. It will create another remote event receiver in your web project.

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. On the other hand, 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.

Show:
© 2014 Microsoft