Sharepoint 2013 : Packaging and distributing apps (part 5) - Trapping app lifecycle events

One favorable aspect of the SharePoint app model for developers is the ability to design a cloud-hosted app with custom server-side code that is automatically executed when an app is installed, upgraded, or uninstalled. By taking advantage of the ability to add code behind these three app lifecycle events, you can program against the host web and the app web with logic to initialize, update, and cleanup site elements in the SharePoint environment. These app lifecycle events also provide the necessary triggers for updating the custom database used by provider-hosted apps and autohosted apps.

The architecture of app events is based on registering app event handlers in the app manifest that cause the SharePoint host environment to call out to a web service entry point in the remote web. Due to the architecture’s reliance on a server-side entry point, app events are not supported in SharePoint-hosted apps. Therefore, you can only use the app events in autohosted apps and provider-hosted apps.

It’s relatively simple to add support for app events to the project for an autohosted app or a provider-hosted app. The property sheet for the app project contains three properties named Handle App Installed, Handle App Uninstalling, and Handle App Upgrade, as shown in Figure 9.

Figure 9. The property sheet for an app project provides Boolean properties for enabling lifecycle events.

The default value for each of these app event properties is false. The first time you change one of these properties to a value of true, Visual Studio 2012 adds a web service entry point into the web project with a name of AppEventReceiver.svc. Visual Studio 2012 also adds the required configuration information into the app manifest file, as well. If you enable all three events, the <Properties> element within <App> element of the app manifest will be updated with the following three elements:

<InstalledEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</InstalledEventEndpoint>
<UninstallingEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</UninstallingEventEndpoint>
<UpgradedEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</UpgradedEventEndpoint>

After you have enabled one or more of the app events, you can then begin to write the code that will execute when the events occur. You write this code in the code-behind file named AppEventReceiver.svc.cs. If you examine this file, you will see that Visual Studio 2012 has created a class shown in the following code that implements a special interface that the SharePoint team created for remote event handling named IRemoteEventService:

public class AppEventReceiver : IRemoteEventService {
  public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {}
  public void ProcessOneWayEvent(RemoteEventProperties properties) { }
}

The IRemoteEventService interface is used with app events and also with other types of remote event handlers, as well. There are two methods named ProcessEvent and ProcessOneWayEvent. The SharePoint host environment makes a web service call which executes the ProcessEvent method when it needs to inspect the response returned from the remote web. The ProcessOneWayEvent method is called for cases in which the SharePoint host environment needs to trigger the execution of code in the remote web but doesn’t need to inspect the response. App events always trigger to the ProcessEvent method, so you can leave the ProcessOneWayEvent method empty in the AppEventReceiver.svc.cs file.

If you have registered for the AppInstalled event, the ProcessEvent method will execute whenever a user is installing the app. It is critical to supply robust error handling because an unhandled exception will be returned to the SharePoint host environment and cause an error in the app installation process.

When you implement the ProcessEvent method, you must return an object created from the SPRemoteEventResult class, as demonstrated in the following:

public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {
  // return an SPRemoteEventResult object
  SPRemoteEventResult result = new SPRemoteEventResult();
  return result;
}

The SPRemoteEventResult class was designed to make it possible for code in the remote web to relay contextual information back to the SharePoint host environment. For example, imagine that you have detected that the installer’s IP address is located in a country that you do not want to support. You can tell the SharePoint host environment to cancel the installation process and pass an appropriate error message, such as shown here:

SPRemoteEventResult result = new SPRemoteEventResult();
result.Status = SPRemoteEventServiceStatus.CancelWithError;
result.ErrorMessage = "App cannot be installed due to invalid IP address";
return result;

The ProcessEvent method passes a parameter named properties, which is based on a type named RemoteEventProperties. You can use this parameter to access important contextual information such as the URL of host web and security access token required to call back into the SharePoint host environment. Example 1 shows that the properties parameter also provides an EventType property with which you can determine which of the three app events has caused the ProcessEvent method to execute.

public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {

  // obtain context information from RemoteEventProperties property
  string HostWeb = properties.AppEventProperties.HostWebFullUrl.AbsolutePath;
  string AccessToken = properties.AccessToken;

  // handle event type
  switch (properties.EventType) {
    case RemoteEventType.AppInstalled:
      // add code here to handle app installation
      break;
    case RemoteEventType.AppUpgraded:
      // add code here to handle app upgrade
      break;
    case RemoteEventType.AppUninstalling:
      // add code here to handle app uninstallation
      break;
    default:
      break;
  }

  // return an SPRemoteEventResult object
  SPRemoteEventResult result = new SPRemoteEventResult();
  return result;

}

Note that debugging app event handlers can be especially tricky to set up and in many situations it doesn’t work at all. That’s because the SharePoint host environment must be able to call back into the remote web. For cases in which you have installed the app into an Office 365 tenancy for testing, it is a web server in the Office 365 environment that will be issuing the call to the remote web. This web server hosted in the Office 365 environment must be able to locate and access the web server that is hosting the remote web. Therefore, attempting to debug an app event handler for which the remote web is configured to use a host name such as localhost or to use a host domain name that only resolves to the proper IP address inside your testing environment will not work.