Handling events in apps for SharePoint
Get a quick overview of how to handle events that occur in cloud apps for SharePoint.
Last modified: July 01, 2013
Applies to: apps for SharePoint | Office 365 | SharePoint Server 2013
To handle events in a cloud app for SharePoint, you create remote event receivers and app event receivers. Remote event receivers handle events that occur to an item in the app, such as a list, a list item, or a web. These events resemble those in a traditional SharePoint solution, except that they can work with the remote components of the app for SharePoint. App event receivers handle events that occur to the app itself, such as when it's installed, uninstalled, or upgraded.
As of this release, remote event receivers and app event receivers work only with cloud apps for SharePoint (that is, autohosted and provider-hosted apps). These receivers don't work with SharePoint-hosted apps for SharePoint.
Remote event receivers for cloud apps for SharePoint
If you create a remote event receiver, your cloud app can respond when a user adds, changes, or deletes a list, a list item, or a web. For example, you can prevent users from deleting a key item from a list, and you can track which users add lists to your app. To add a remote event receiver, choose the Remote Event Receiver project item template, and then specify the type of remote event receiver that you want to add. For example, you can create a List Item Events receiver, which fires when a user adds or deletes a list item. You can view the available events when you create a remote event receiver, or you can view them later by opening Solution Explorer, choosing the node for the receiver, opening the Properties window, and then looking in the SharePoint Events section. When you create a remote event receiver, you must also specify the source of the events that you want that receiver to handle. For a List Item Events receiver, you can specify any list (such as Announcements, Calendar, or Contacts) in the current solution or on the site at the Site Url property of the app for SharePoint project. For more information, see How to: Create a remote event receiver and How to: Create an event receiver for an app for SharePoint.
To debug an app for SharePoint project that has remote event receivers you can open it on a computer that has local installations of Visual Studio and SharePoint. However, the event receivers for such an app will work in remote deployments after you deploy it. You can also debug remote events in an app for SharePoint project by using the Windows Azure Service Bus. For more information, see the Debugging remote events section in the topic Developing apps for SharePoint on a remote system.
When you add a remote event receiver to a cloud app for SharePoint, the following actions occur:
To process remote events, your solution needs a web application, so one is added if one doesn't already exist. That application is then used as the host web application for the app for SharePoint.
A web service, such as RemoteEventReceiver1.svc, is added to the web application to handle the events that you specified when you added the remote event receiver to the app for SharePoint. The web service contains a code file to handle the remote events.
After you create the remote event receiver, you add code to the code file for the web application service to handle the events. By default, the code file contains two methods: ProcessEvent() and ProcessOneWayEvent(). ProcessEvent() handles events that occur before an action occurs, such as when a user adds or deletes a list item. 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.
A project item for the remote event receiver is added to the app for SharePoint project. The Elements.xml file for the remote event receiver references the web service in the web application and the remote events that you specified. The following example shows an Elements.xml file that handles the addition or deletion of a list item:
<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <Receivers ListTemplateId="104"> <Receiver> <Name>RemoteEventReceiver1ItemAdding</Name> <Type>ItemAdding</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> <Receiver> <Name>RemoteEventReceiver1ItemDeleting</Name> <Type>ItemDeleting</Type> <SequenceNumber>10000</SequenceNumber> <Url>~remoteAppUrl/RemoteEventReceiver1.svc</Url> </Receiver> </Receivers> </Elements>
To change the events that the remote event receiver handles, open Solution Explorer, open the Properties window for the remote event receiver, expand the SharePoint Events node, and then set only the events that you want to handle to True.
When you configure cloud-based apps for SharePoint, you must ensure that the correct access tokens are available. For more information, see Authorization and authentication for apps in SharePoint 2013.
App event receivers for cloud apps for SharePoint
If you create an app event receiver, you can respond when an event occurs to an app for SharePoint, such as when it's installed, uninstalled, or upgraded. This technique is useful if, for example, you want to automatically perform a cleanup operation, send a notification mail, or add an entry to a log file after a user installs an app for SharePoint. You can handle only a few app events, so you can respond in relatively few ways with an app event receiver on the app web. For example, you can’t write an item to a list in the Handle App Installed event because no lists exist on the app web when the user first installs the app. You must also include error handlers in any app event receivers, because unhandled exceptions can prevent the app from installing, uninstalling, or upgrading.
You can display a list of all of the app events by opening Solution Explorer, opening the Properties window for the app for SharePoint, and then expanding the App for SharePoint Events node. You can handle the following events:
Handle App Installed
Handle App Uninstalling
Handle App Upgraded
To handle an event, set its property value to True. To disable an event, set its property value to False. For more information, see How to: Create an app event receiver.
When you add an app event receiver to an app for SharePoint by setting one of its App for SharePoint Events to True, the following actions occur:
A web service that's named AppEventReceiver.svc is added to the web application. This service contains a code file to handle the app events. The contents of this service match the contents of the web service for a remote event receiver, including the ProcessEvent() and ProcessOneWayEvent() methods. The code in these events runs when the app events that you specified occur.
The following entry is added to the Properties section of the AppManifest.xml file: <InstalledEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</InstalledEventEndpoint>. This entry associates the app event receiver to its service in the web application.
If you remove an app event receiver by setting its property to False in the Properties window, the app event entry is removed from the AppManifest.xml file, but the web application project is retained.