SharePoint 2013: How To Develop Remote Event Receivers For App Events

In this second post on Remote Event Receivers we are going to explore the implementation details of “Remote Event Handlers for App Events”. In case you need to recall the concepts related to “Remote Event Receivers”, you can refer to my first post in this series,

SharePoint 2013: Remote Event Receivers.

In order to show case the implementation details of Remote Event Handler for App Events, let’s start with creating a Provider Hosted App by using the following steps:

Create New Project in Visual Studio using “App for SharePoint” Project template,

create

Specify Host Web URL and choose “Provider-hosted” as App Type,

host

Choose “ASP.Net Web Forms Application” as Project Template to create Remote Web for our Provider Hosted App,

choose

Specify Certification Details based on the configuration of Provider-Hosted App Development Environment. Following details needs to be provided:

Certificate Location
Password
Issuer ID

config

Once all the above steps are executed successfully we will get a new Solution created with two projects:

PH-AppEventLifeCycle which is a Provider Hosted App
PH-AppEventLifeCycleWeb which is a Remote Web for App

explorer

Select Provider Hosted App Project and press F4 to see the Project Properties. In the Project Properties look for “App for SharePoint Events” section and enable all events that you want to get handled by Remote Event Receiver.

Here I have set all the three events “Handle App Installed”, “Handle App Uninstalling, “Handle App Upgraded” to True, this setting will allow SharePoint to delegate respective events to the registered Event Receiver.

explorer

In case you need to create an App Web for your Provider Hosted Web (though it is not necessary) you must have at least one Web Scoped Artifact added in the Project as this action will force SharePoint App Framework to provision App Web during the App Deployment.

In this case I have added a Dummy Module deploying some sample file just to force SharePoint to create an App Web for our Provider Hosted App.

explorer

It is noteworthy to look for AppManifest.xml file as most of the configuration settings for an App are derived from here only.

In General Tab, we have two noteworthy Properties:

Start Page: It allows you to set any Page as App Start Page. In this case we have set it to point to the Default.aspx Page in Remote Web.
Query String : Allows adding additional information as Query String Parameters while redirecting to the Start Page

page

In Permission Tab, we can specify the set of Permissions that an App will need to perform desired tasks.

At the time of App Installation, App will request this permission set to be granted and that we will see a few steps down the line.

app

Now the very next thing is to investigate the constitution of Remote Web Project “PH-AppEventLifeCycleWeb”

explorer

In this Project we have following important Files to look for:

Default.aspx: This is the start page for Provided Hosted App as we set it in earlier steps. In this page we can perform actions that are desired for a specific task. For example we can provide UI for end users to interact with the App.

In this demo the code sample is reading the title of the Hosting Web as follows:

Steps 1: Getting URL of the Host Web by reading “SPHostUrl” Parameter

Steps 2: Instantiating Client Context by CallingGetS2SClientContextWithWindowsIdentity method provided by SharePoint Infrastructure by means of TokenHelper.cs Class

Step 3: Once Client Context is Instantiated, we can make use of Managed CSOM to load the Web and read its Title Property as shown below

code

Scripts: We can go with the default set of scripts added during creation of the project, else we can add any desired script file to it

explorer

AppEventReceiver.svc : This Service class has been added to the Project as soon as you add a “Remote Event Receiver” Project Item to the Project

explorer

Let’s walk through through the code file and see what we got.

Step 1: Add “Microsoft.SharePoint.Client.EventReceivers” Namespace which is needed for Remote Service to handle Remote Events and inherit the class from “IRemoteEventService”.

Step 2: Override the method ProcessEvent

Step 3: Specify Remote Event Service Status if you want to continue or reject, so that execution succeed or revert back

Step 4: Perform actions as per the business requirement. Here I am adding logs to Windows Event Log

Step 5: Return the Event Result back to SharePoint

code

Step 1: Override the method ProcessOneWayEvent

Step 2: Perform actions as per the business requirement. Here I am adding logs to Windows Event Log

code

Web.config: In Web.config file, there are a couple of “AppSettings” that are important to take note of-

ClientId: Generated Automatically by Visual Studio for development perspective. At the time of App registration this can be regenerated and used accordingly.

ClientSigningCertificatePath: Specify the path of Client Certificate exported during environment configuration.

ClientSigningCertificatePassword: Specify the path of Client Certificate Password specified to protect the Certificate during environment configuration.

IssuerId: Specify the path of Issuer ID generated during environment configuration

code

With this we are done with inspection to all of the important files in our solution.

Now it is time to Build the Solution and Run it.

In the below screen shot we can see the Client ID is generated by Visual Studio Tools during Build Process.

code

Once the Solution Build & Run successfully, the App Framework looks for theAppManifest.xml and find a permission set to be granted by App User on the Host Web.

So we have to grant permissions as specified in Permissions Tab ofAppManifest.xml file and in order to grant the permissions click “Trust It”.

explorer

As soon as we grant the permissions, App Launcher looks for the App Start Page as specified in General Tab of AppManifest.xml file and Redirect the user to that page.

If we notice the URL in below screen shot, we find the App Start Page isdefault.aspx of Remote Web as specified in AppManifest.xml file for the App.

xml

If we investigate the Site Structure using any tool like SharePoint Manager (one of my favorites), we can see an App Web by the name “PH-AppEventLifeCycle”is also provisioned due to the presence of Dummy Module we added to the Project earlier.

module

After App is getting installed successfully, we can also see an event log is added to the Windows Application Log as shown below based on the message we placed in the “AppEventReceiver.svc” code file:

file

Likewise while the App is uninstalling, we can see an event log is added to the Windows Application Log as shown below based on the message we placed in the “AppEventReceiver.svc” code file:

file

This simple walkthrough can help you to understand how to deal with the App Events.

We can utilize these semantics under different business cases liking registering Event Receivers for existing lists or notifying users and so on.

Hope you find it helpful.