A new feature in Project Server 2013 is the Remote Event Handlers. Those who worked with 2010 version know that to write a server event one needed to:

– create an assembly containing the server event handlers
– create some code to register the server event handlers with the  Project Server events
– deploy the assembly to GAC on all the servers in the Project Server farm.

The easiest way to accomplish these tasks was to package everything in a solution that needed to be deployed in the farm. A feature Activate/ Deactivating handlers would take care of registering and unregistering the event handlers with the Project Server.

Now in 2013 these still apply, but there is also the possiblity to create so-called Remote Event Handlers. This new feature enables responding to server side events without having to deploy any code in the farm. This is especially useful for those having their Project instance in the cloud (Office 365), or wherever company IT policies prohibit deploying code to the SharePoint farm.

To create a remote event handler, the tasks above become:

– create a WCF service (in an existing web application, or in a new web application) that implements the desired event(s)
– have some code to register the endpoint to this WCF service with the Project Server events

The WCF service can be hosted in a  web application on premises or in cloud as long as there’s direct HTTP(s) communication between the Project Server farm and the Remote event handler it will work.

Below there is a small code sample to illustrate this concept. We will be connecting to a Project Server farm, and write a remote event handler for the ProjectCreating event which will fail creation for those projects that do not respect certain naming convention. Let’s assume that our managers don’t want the word “New” in the project name.

We start with a New empty web application project – let’s call it ProjServerRemoteEventDemo, to which we add 2 things – an empty Web Form page (default.aspx) and a WCF service called ProjectEventReceiver.svc.

We also need to add a few references:

– Project Server library (Microsoft.Office.Project.Server.Library.dll)
– Project Server event receivers definitions (Microsoft.Office.Project.Server.Event.Receivers.dll)
– Project Server CSOM (Microsoft.ProjectServer.Client.dll) which in turn requires
– SharePoint CSOM (Microsoft.SharePoint.Client.dll) and
– SharePoint CSOM runtime (Microsoft.SharePoint.Client.Runtime.dll).

These files can be easily found browsing to C:WindowsMicrosoft.NETassemblyGAC_MSIL in their folders.

Default.aspx will serve as an interface to the register/unregister functions. We will use CSOM to manage event registration:

In the code behind, registration management is done on btnRegister_Click and btnUnregister_Click. The brief code for these two methods is below:

Register_Click:


ProjectContext pc = new ProjectContext(ProjectServerUrl);
pc.EventHandlers.Add(new EventHandlerCreationInformation()
{
EndpointUrl = BaseUrl + "/ProjectEventReceiver.svc",
Id = EventHandlerUid,
Name = "Project OnCreating Demo Event",
EventId = (int)PSEventID.ProjectCreating,
Order = 1,
CancelOnError = true
});
pc.EventHandlers.Update();
pc.ExecuteQuery();


Let’s detail a bit:

ProjectServerUrl is the address for your PWA instance (say http://projects.contoso.com/pwa)
BaseUrl is the address where the event receiver is published (say http://cloud-app.contoso.com/)
Some important properties that are set in the EventHandlerCreationInformation class are:
–  Id: this gives an unique event registration Id – it will allow us to retrieve the event later when we want to unregister it.
– EventId: this specifies which event are we attaching to, in our case PSEventId.ProjectCreating
– Order: event handler calling order
– EndpointUrl: where is the WCF endpoint that will handle the event.

Unregister_Click:

ProjectContext pc = new ProjectContext(ProjectServerUrl);
pc.Load(pc.EventHandlers);
EventHandler evh = pc.EventHandlers.GetByGuid(EventHandlerUid);
pc.Load(evh);
pc.ExecuteQuery();
pc.EventHandlers.Remove(evh);
pc.EventHandlers.Update();
pc.ExecuteQuery();

A very important thing to note is that the registration and unregistration of event handlers is not a synchronous process. It is done in a timer job that runs quite frequently but still there will be a few seconds delay from the moment the ExecuteQuery() returns and the actual event registration.

Now that we have finised with registration, let’s concentrate on the event handler itself.

As expected, for the eventing subsystem in the Project Server to be able to talk to our WCF service, the latter needs to implement a specific contract. In our case this contract is IProjectEventReceiverRemote which is defined in the Microsoft.Office.Project.Server.Event.Receivers.dll assembly togheter with other contracts. These are distinguished by the termination “Remote”.

The actual implemetation is straightforward:


public class ProjectEventReceiverRemoteService : IProjectEventReceiverRemote
{

…

public ProjectPreEventArgs OnCreatingRemote(Microsoft.Office.Project.Server.Library.PSContextInfo contextInfo, Guid eventHandlerUid, ProjectPreEventArgs e)
{
if (e.ProjectName.Contains(“New”))
{
e.CancelReason = “Naming requirements not met. Please remove ‘New’ from project name”;
e.Cancel = true;
}
return e;
}

…
}

Having these, the project is complete. Let’s  compile and start the web application, then register the event. when a project that has “New” in name is created, this is what we get:

The sample solution files are available: ProjServerRemoteEventDemo.