Project Server events provide a great way to extend the functionality of the product by custom logic. For example, you can write code that will be executed if the web site of the project was created and customize the site with features that can not be integrated into the project site template itself, or respond to the deletion of the project and perform some kind of housecleaning, that is not part of the default deletion, like removing custom created project-specific SharePoint groups.
There is a page in the Central Administration that supports the event handler maintenance (see Central Administration / General Application Settings / PWA Settings (Manage) / Server Side Event Handlers, illustrated below).
There is unfortunately a major Application Lifecycle Management (ALM) related issue with this approach: It is a manual process that cannot be easily automated as part of the solution deployment.
Alternatively, one can deploy event handlers as part of a SharePoint package, as stated in the Project Server entity provisioning schema section of the Project Server programmability article. This method is described and demonstrated in the presentation Developer to developer – learn the Microsoft Project Online and Server extensibility (authors: Bill Avery and Chris Givens), see further details in section “Project Server App Packages” beginning at slide 75 of the presentation.
A sample of the Project Server entity provisioning XML including an event handler registration:
- <?xml version="1.0" encoding="utf-8" ?>
- <ProjectServerEntities xmlns="http://schemas.microsoft.com/sharepoint/">
- <EventHandlers>
- <EventHandler Id="6B92EF26-25CA-4716-9352-67FC2EF57BE3" Name="PWSCreated">
- <EventName>WssInteropWssWorkspaceCreated</EventName>
- <Description>Called when a new PWS site was created</Description>
- <EndpointUrl>http://dummysite.org</EndpointUrl>
- <AssemblyName>$SharePoint.Project.AssemblyFullName$</AssemblyName>
- <ClassName>Customer.EPM.PSEventHandler</ClassName>
- <CancelOnError>false</CancelOnError>
- </EventHandler>
- </EventHandlers>
- </ProjectServerEntities>
Note the EndpointUrl element, that contains only a dummy value in this case. In this case we use a local event handler implemented in a custom assembly, however we could use remote event handlers as well. This element is optional by the XSD of the Project Server entity provisioning schema, however, if we did not include this in the XML, we would receive a deployment error on the feature activation:
Value cannot be null. Parameter name: uriString
An empty value causes a similar error in the feature receiver:
Invalid URI: The URI is empty.
If the URL is not well formatted:
Invalid URI: The format of the URI could not be determined.
Formerly I applied this approach to deploy my event handlers, lookup tables and enterprise custom fields, but it turned out quickly, that whenever I deploy a new version of the package, the former entities are retracted and deployed again, resulting in a loss of information, for example, on tasks, projects and resources that already had a re-deployed enterprise custom fields assigned. In a developer environment it was only inconvenient, but in test and production system I found that simply unacceptable.
So I decided to write my own tools to list, register and remove Project Server event handlers using the managed client object model.
First, let’s see how to enumerate the event handlers and dump the most important properties:
- using (var projectContext = new ProjectContext(pwaUrl))
- {
- projectContext.Load(projectContext.EventHandlers, ehs => ehs.Include(
- eh => eh.Id,
- eh => eh.Event,
- eh => eh.AssemblyName,
- eh => eh.ClassName,
- eh => eh.Order));
- projectContext.ExecuteQuery();
- projectContext.EventHandlers.ToList().ForEach(eh =>
- Console.WriteLine("Event \r\nEvent Handler [Id: {3} AssemblyName: {4} ClassName: {5} Order: {6}]\r\n",
- eh.Event.SourceName, eh.Event.EventName, eh.Event.Id, eh.Id, eh.AssemblyName, eh.ClassName, eh.Order));
- }
The output in our case:
Using the code below, we can register our custom event handler. To be able to use the predefined values in the PSEventID enumeration, you should include a reference to the Microsoft.Office.Project.Server.Library.dll assembly.
- using (var projectContext = new ProjectContext(pwaUrl))
- {
- var ehci = new EventHandlerCreationInformation
- {
- Id = projDeletedEventHandlerId,
- Name = "ProjDeleting",
- AssemblyName = "Customer.EPM, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b28db3dcb95229e1",
- ClassName = "Customer.EPM.ProjectEvents",
- Description = "Called when a project is being deleted",
- EventId = (int)PSEventID.ProjectDeleting, // value is 49, handling ProjectEventReceiver.OnDeleting
- Order = 100,
- CancelOnError = false
- };
- projectContext.EventHandlers.Add(ehci);
- projectContext.EventHandlers.Update();
- projectContext.ExecuteQuery();
- }
Note: this code only submits the requests for the event handler registration- The registration itself is performed asynchronously in a background process, so there is a delay after running the code until the event handler appears in the list.
Finally, if you don’t need the event handler any more, you can remove it using the following code (assuming you already know the ID of the event handler, for example, from the output of the event handler enumeration example):
- var projDeletedEventHandlerId = new Guid("0FB1389D-E620-4062-A99B-9E5716CC958E");
- using (var projectContext = new ProjectContext(pwaUrl))
- {
- var eh = projectContext.EventHandlers.GetByGuid(projDeletedEventHandlerId);
- projectContext.EventHandlers.Remove(eh);
- projectContext.EventHandlers.Update();
- projectContext.ExecuteQuery();
- }
A similar code for unregistering the event can be found here, but the sample above is a bit simpler, using only a single ExecuteQuery call. You might need the double call if you don’t know the ID of the event handler yet. In this case you should look up the event handler by name, or by the type of the event it handles first, and it requires a former ExecuteQuery call to get the complete list of the event handlers. Then in the next step, you can already remove the event handler as illustrated above.
