Export (0) Print
Expand All

Handle events in apps for SharePoint

apps for SharePoint

Get a quick overview of how to handle events in provider-hostedapps for SharePoint.

Last modified: March 26, 2015

Applies to: apps for SharePoint | Office 365 | SharePoint Server 2013

Your custom code can handle three categories of events in provider-hosted apps:

  • List events, such as the adding or deleting of a list on a website.

  • List item events, such as the editing of an item in a list.

  • App events, such as the installation of an app.

SharePoint-hosted apps for SharePoint do not support event handling, but you can turn a workflow into a kind of list or list item event handler by setting an event to trigger the workflow. See Workflows in SharePoint 2013. Workflows cannot be triggered by app events, so app events cannot be handled with a SharePoint-hosted app.

Note Note

Note for veteran SharePoint developers: website events and site collection events are not supported in apps for SharePoint.

There are two kinds of events:

  • Before events are triggered before the SharePoint infrastructure does any of it's own handling of the event (including committing changes to the content database). In SharePoint custom before event handlers always execute synchronously. Among other purposes, they can be used to cancel the event. For example, if an app has a function for deleting a list, a handler for the list deleting event can cancel the deletion if certain conditions are not met. If the event is part of a sequence of events, cancelling it prevents any of the later events from occurring at all. For example, if your handler for the ItemAdding event cancels the event, the ItemAdded event, which normally comes later, is not triggered.

  • After events are triggered after the SharePoint infrastructure does any of it's own handling of the event. In SharePoint, remote after event handlers, for list and list item events, always execute asynchronously. (App events are an exception.) Among other purposes, they can be used to log events.

To handle list and list item events, you create remote event receivers (RERs), which are web services that run externally to the SharePoint farm or SharePoint Online. The URL of the RER service is registered for the events it handles. There are two ways to register a handler:

  • Events in the host web are registered programmatically with the CSOM (client-side object model) or the SharePoint REST API. This task is typically done in "first run" logic in the app or in a handler for an app event. (See Handling app events later in the article for an overview of app events.) For a code sample that programmatically registers a list event, see OfficeDev/PnP/Samples/Core.EventReceivers.

  • Events in the app web are usually registered in a Feature of the app web with some simple XML markup. Details of how to create the markup and the service are in Create a remote event receiver in apps for SharePoint. It is also possible to register app web events programmatically.

Note Note

Note for veteran SharePoint developers: RERs have the same purpose as event receivers in farm solutions; but event receivers have custom code that runs on the SharePoint servers, so they cannot be used in apps for SharePoint.

Your app can handle the following list and document library events. Events ending in "ing" are before (synchronous) events and those ending in "ed" are after (asynchronous) events.

ListAdding

ListAdded

ListDeleting

ListDeleted

FieldAdding

FieldAdded

FieldDeleting

FieldDeleted

FieldUpdating

FieldUpdated

The field update events are about changing the properties of a field (column) on a list, such as whether it is sortable, not about changing the data in the field.

Your app can handle the following list item events.

ItemAdding

ItemAdded

ItemUpdating

ItemUpdated

ItemDeleting

ItemDeleted

ItemCheckingOut

ItemCheckedOut

ItemCheckingIn

ItemCheckedIn

ItemUncheckingOut

ItemUncheckedOut

ItemAttachmentAdding

ItemAttachmentAdded

ItemAttachmentDeleting

ItemAtttachmentDeleted

ItemFileMoving

ItemFileMoved

ItemVersionDeleting*

ItemVersonDeleted*

ItemFileConverted

Note Note

*These two new events may not be available in the Visual Studio UI. If not, pick ItemDeleting or ItemDeleted and then manually change the names.

When you are working in Visual Studio, and you add a RER to a app for SharePoint project, the Office Developer Tools for Visual Studio do the following:

  • A web service file, 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 to which you add your handling code:

    • ProcessEvent() handles "before" events (such as those in the left-hand columns in the tables earlier in the article) and it returns an object to SharePoint that reports on whether it should cancel the event or let it proceed.

    • ProcessOneWayEvent() handles "after" events. It runs asynchronously and does not return anything to SharePoint.

    When a registered event occurs, SharePoint calls the appropriate method in your service and passes an object that provides some context information for your code. For example, the event type (from one of the two tables earlier in the article) is identified, so that your code can branch to the logic that is appropriate for the event.

  • 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.

Note Note

For additional information about RERs, including some troubleshooting information, see Remote event receivers in SharePoint 2013 FAQ.

App events are also handled by remote web services, but they are configured differently in the app package from list and list item RERs, so they are treated as a separate category of component. For an app event, the remote web service is registered in the app manifest, not in an app web Feature. The app doesn't even have to have an app web. There are three app events as described in the next sections.

AppInstalled event

The AppInstalled event runs immediately after SharePoint has finished everything that it needs to do when the app is installed, but before the user is notified that installation is complete. Although this is an after event, SharePoint runs your handler synchronously. The app is not available for use until after your handler has completed and your handler can cancel the installation (which will cause SharePoint to roll back everything it has done as part of the installation). In fact, it is a best practice to catch any errors in your handler and instruct SharePoint to roll back the installation. See Include rollback logic and "already done" logic in your app event handlers for more information.

Note Note

When you install an app with Tenant scope, it is installed to the app catalog site collection and the AppInstalled event runs then and only then. The app is visible in multiple web sites in the tenancy, but the event does not run separately for each of these.

Besides canceling an app installation, this event can be used for many other purposes including:

  • Install SharePoint components to the host web that cannot be declaratively installed with the host web Feature, such as lists or subwebs.

  • Programmatically register list and list item event handlers with the host web or app web.

  • Set app-instance-relative initialization settings. For example, your app can have an app web property bag for holding settings that vary from one instance of the app to another. Your AppInstalled handler can write varying values to the property bag, based on, say, the site type of the host web (such as Team Site or Blog site).

    Note Note

    Checking to see if the host web is an AppCatalog site is a good way to detect whether the app has been installed with tenant scope. See Tenancies and deployment scopes for apps for SharePoint.

  • Perform app-instance-relative configuration in the app's remote web application, such as adding a table to a database.

Important note Important

Your implementation of the AppInstalled event must complete within 30 seconds or the SharePoint installation infrastructure will think it has failed. The infrastructure will rerun the event, and repeat your code from the beginning, up to three additional times. After four timeouts, SharePoint will roll back the entire app installation. The full implications of these facts are discussed in See Include rollback logic and "already done" logic in your app event handlers for more information.

AppUninstalling event

The AppUninstalling event does not run when the app is removed from the host web. Removal of an app only moves the app to the user's recycle bin. Two more steps are required before the AppUninstalling event is triggered. First, a user must remove the app from the recycle bin, which moves it to the second stage recycle bin. Second, a user must remove the app from the second stage recycle bin. This last task triggers the AppUninstalling event. The AppUninstalling event is synchronous and you can use it to cancel the uninstallation, which would leave the app in the second stage recycle bin.

The main purpose of a handler for this event is to delete or recycle things that were deployed with a AppInstalled (or an AppUpdated) handler. SharePoint cannot delete these things, or move them to the recycle bin, because it doesn't know about them, at least not as components of the app. It is usually a good practice to remove these things. But you don't want to delete things that still have a useful life after the app is gone: if a list or website created by your AppInstalled handler is still going to be used, don't delete it in your AppUninstalling handler.

AppUpgraded event

The AppUpgraded event runs immediately after SharePoint has finished everything that it needs to do when the app is updated to a new version, but before the user is notified that updating is complete. Like the AppInstalled event, it is an after event, but is essentially synchronous and it is a best practice to catch errors and notify SharePoint to roll back the update.

Some examples of what a handler for this event can do:

  • Add, change, or remove app components from the host web.

  • Do things in the app web that aren't possible with the declarative update semantics in an app web Feature. For example, you cannot delete anything with the declarative update markup, but you can do so programmatically in an AppUpgraded handler.

  • Make changes to app-instance-relative components in the app's web application or remote database.

Detailed instructions for creating app event handlers is in Create an app event receiver in SharePoint 2013.

Include rollback logic and "already done" logic in your app event handlers

If SharePoint encounters an error when processing any of the three app events, it will cancel the event and roll back any changes it has made in connection with the event. Your app event handlers have to integrate with this system because if the part of the event that you are implementing fails, you want the whole event to roll back, rather than continue and leave things in a possibly corrupt state. Here's what your handler usually has to do:

  • Tell SharePoint that an error has occurred. The SOAP message that your app event handling web service returns to SharePoint will have a Status property that can have the values of Continue, CancelWithError, or CancelWithoutError. Either Cancel* status tells SharePoint to roll back the event.

  • Roll back what the handler has already done before the handler encounters the error. SharePoint can't usually do this for you because it doesn't know what your handler did. This isn't a universal rule. For example, if an app installation is canceled, SharePoint will delete the entire app web, so there's no point in an AppInstalled event handler reverting anything it has done to the app web. But it usually should roll back things it did to the host web or to remote components of the app.

Note Note

Special note about the AppUninstalling event: The preceding points apply to the AppUninstalling event as much as to the other two app events. For example, if your handler for the uninstalling event deletes a row in a remote database, and then encounters an error, the row needs to be restored. Since your service will be sending a cancel message to SharePoint, the app will not be removed from the recycle bin. If it is restored from there and used again, it may fail to work without that database entry.

However, your AppUninstalling handler completes before SharePoint removes the app from the recycle bin. So, if SharePoint itself encounters an error and needs to cancel the removal, there is no way for your handler to undo what it has done.

If SharePoint doesn't receive a results message from your handler in 30 seconds, it will call the handler again. It gives up entirely, and rolls back the event, after three retries (four tries in all). Each time it calls the handler, your code starts again from the beginning. But you generally don't want your handler to redo things it has already done, such as create a list on the host web, and you can't know if your rollback logic was completed, or even triggered, before the handler timed out. For this reason, your handler logic should not take any action without first checking whether the action has already been done, unless it would be harmless to do it again.

Installation and updating errors can be seen in the SharePoint UI, as shown in the following graphic.

Steps to see app installation errors in SharePoint.

App event handler architecture strategies

Expressed in pseudo-code, your handler should usually be structured something like the following. If an error occurs in the Try section, the Catch and Rollback section should be invoked. (This may happen automatically depending on the language and framework.)

Try
    If X not already done,
        Do X.
Catch
    Send cancel message to SharePoint.
    If X not already undone,
        Undo X.

However, implementing your rollback and "already done" logic in your web service can slow down the handler. Both your installation and rollback logic usually make changes to something more-or-less remote from the web service, such as the SharePoint host web or a back end database. If your installation and rollback code is split between the Try and Catch sections, then the service is making separate calls to the remote components, often several such calls in each section. The best practice is usually to implement the installation and rollback logic on the remote component itself in a procedure that can be called from your handler in your Try section. The procedure should return a success or failure message, and if it reports failure, code in your Try section invokes the Catch section (by, say, throwing an exception). The only thing the Catch section does is notify SharePoint. We'll call this the handler delegation strategy. The following pseudo-code illustrates the strategy:

Try
    Call the "Do X" procedure on remote platform.
    If remote platform reports failure, call Catch.
Catch
    Send cancel message to SharePoint.

The "Do X" procedure, that executes on the remote system, would itself contain the rollback and "already done" logic like the following.

Try
    If X not already done,
        Do X.
        Set success flag to true.
Catch
    If X was done before error,
        Undo X.
    Set success flag to false.
Send
    Return success flag to the event handler.

For example, if your handler needs to take action on an SQL Server database, you can install a stored procedure on the SQL Server that uses a TRY-CATCH block to implement installation-rollback logic. with IF-ELSE blocks to implement "already done" logic.

The SharePoint app model doesn't provide a way to store custom server-side code on SharePoint and invoke it from the CSOM (client-side object model). But the CSOM does provide a way to bundle try-catch and if-then-else logic and send it to the server for execution. For a detailed example of a app event handler that uses the handler delegation strategy to add a list to a host web, see Create an app event receiver in SharePoint 2013. For a code sample, see OfficeDev/PnP/Samples/Core.AppEvents.HandlerDelegation.

You cannot always use the handler delegation strategy. For example, when your handler is calling out to more than one component, such as to a database and the SharePoint host web, there is a chance that one could complete successfully and then the other fail. In this scenario, the rollback logic for the first component doesn't run if you designed it with the handler delegation strategy. For this reason, if you are calling to the components synchronously only the last one called can use the handler delegation strategy. If they are called asynchronously, you can't use that strategy in any of them. For a sample of an app event handler that does not use the handler delegation strategy, see OfficeDev/PnP/Samples/Core.AppEvents.

TipTip

If the AppInstalled event fails, SharePoint will delete the app web, if there is one; and if the AppUpated event fails, SharePoint will restore the app web to its pre-update state. For this reason, your handlers never need to rollback actions they take on the app web. If you handler performs actions on both the host web and the app web, it should deal with the app web first. Doing so makes it safe to use the handler delegation strategy for the host web. Even if the app web actions succeed and the host web actions fail, there is no rollback logic that goes unexecuted.

Show:
© 2015 Microsoft