Writing and Debugging Event Handlers for Project Server 2007

Summary: Learn how to write and debug event handlers for Microsoft Office Project Server 2007 for use in the Project Server Eventing service.

Office Visual How To

**Applies to:**2007 Microsoft Office system, Microsoft Office Project Server 2007

Joel Krist, Akona Systems

October 2007

Overview

The Project Server Eventing service is the key to extending Microsoft Office Project Server 2007 functionality. You can create event handlers and register them programmatically with methods in the Events Web service or through Project Web Access. Each major business object (such as CustomFields, CubeAdmin, LookupTable, Project, Reporting, Security, and TimeSheet) includes multiple events that you can see on the Project Web Access Events page (http://ServerName/ProjectServerName/_layouts/pwa/admin/Events.aspx). Event handlers provide hooks for adding new functionality, customizing existing functionality, and integrating with other applications. Event handlers for pre-events, such as Project Publishing, can check that business rules are followed and cancel an operation if necessary. Event handlers for post-events, such as Project Published, can start a workflow or send saved data to external systems. This Office Visual How To article shows how to write and debug event handlers for Office Project Server 2007.

See It Writing and Debugging Event Handlers for Project S

Watch the Video

Length: 11:40 | Size: 12.3 MB | Type: WMV file

Code It | Read It | Explore It

Code It

This section walks through eight key steps to write and debug event handlers for Project Server 2007. The key steps are:

  1. Creating a class library project in Microsoft Visual Studio 2005.

  2. Adding references to the required assemblies to the Visual Studio project.

  3. Signing the class library assembly with a strong name.

  4. Adding the code that implements an event handler for the project publishing event.

  5. Deploying the event handler assembly to the computer running Office Project Server.

  6. Registering the event handler with Project Server by using Project Web Access.

  7. Testing the event handler.

  8. Debugging the event handler.

Creating a Class Library Project in Visual Studio 2005

To create a class library project in Visual Studio 2005, use the following procedure.

To create a class library project in Visual Studio 2005

  1. Start Visual Studio.

  2. On the File menu, point to New, and then click Project.

  3. In the New Project dialog box, in the Project Types pane, click Visual C# or Visual Basic, and then select the Windows category.

  4. In the Templates pane, click Class Library.

  5. For the project Name, type TestEventHandler.

  6. Specify a location for the project, and then click OK.

    Visual Studio generates a class library project with a single source file in it named Class1.cs or Class1.vb, depending on which language you selected in Step 3.

  7. In Solution Explorer, right-click the source file, and then click Rename. Rename the Class1.cs or Class1.vb source file to PublishingEventHandler.cs or PublishingEventHandler.vb, depending on which language you are using.

Adding References to the Required Assemblies

The event handler described in this article uses both Project Server classes and Windows SharePoint Services classes. To enable these classes to be used in the project, add references to the required Project Server and SharePoint assemblies.

To add references to the required assemblies

  1. If you are running Visual Studio on a computer that has Project Server 2007 installed, do the following:

    1. With the TestEventHandler project open in Visual Studio, on the Project menu, click Add Reference.

    2. By default, the Project Server assemblies are not visible on the .NET tab in the Visual Studio Add Reference dialog box. However, you can browse for the assembly files. In the Add Reference dialog box, click the Browse tab, and then navigate to the \Bin folder in the following path:

      %Program Files%\Microsoft Office Servers\12.0\Bin

    3. Locate the Microsoft.Office.Project.Server.Events.Receivers.dll file and the Microsoft.Office.Project.Server.Library.dll file, press and hold the CTRL key, and select both files.

    4. Click OK to add the references.

    5. On the Visual Studio Project menu, click Add Reference.

    6. In the Add Reference dialog box, on the .NET tab, locate and select the Windows SharePoint Services component (Microsoft.SharePoint.dll).

    7. Click OK to add the reference.

    If you are running Visual Studio on a computer that does not have Project Server 2007 installed, do the following:

    1. On a computer that does have Project Server installed, locate the \Bin folder in the following path:

      %Program Files%\Microsoft Office Servers\12.0\Bin

    2. Copy Microsoft.Office.Project.Server.Events.Receivers.dll and Microsoft.Office.Project.Server.Library.dll from the \Bin folder to a local project folder on the development computer. These two files are required to create the event handler,

    3. The sample event handler also requires the SharePoint assembly. On a computer that has Windows SharePoint Services 3.0 installed, locate the ISAPI folder in the following path:

      %Program Files%\Common Files\Microsoft Shared\web server extensions\12\ISAPI

    4. Copy Microsoft.SharePoint.dll from this path to the same local project folder on the development computer.

  2. After you make local copies of the Office Project Server and SharePoint assemblies, you can add references to them by browsing for the local files. To add references to local copies of the assemblies, do the following:

    1. On the Project menu, click Add Reference.

    2. In the Add Reference dialog box, click the Browse tab, and then navigate to the local folder that contains the copies of the assemblies.

    3. Press and hold the CTRL key, and select the following files: Microsoft.Office.Project.Server.Events.Receivers.dll, Microsoft.Office.Project.Server.Library.dll, and Microsoft.SharePoint.dll.

    4. Click OK to add the references.

    NoteNote

    Applications or components that use the Microsoft.SharePoint.dll assembly must run on the computer where Office Project Server or Project Web Access (with Windows SharePoint Services) is installed. Because you will later copy the TestEventHandler.dll assembly and run it on the computer running Office Project Server, you can develop it on a different computer.

Signing the Class Library Assembly with a Strong Name

You can deploy the event handler assembly either to a special event handler directory or to the global assembly cache. To allow the event handler assembly to be installed in the global assembly cache, it must be signed with a strong name. A strong name consists of the assembly's identity—its simple text name, version number, and culture information (if provided)—plus a public key and a digital signature.

To assign a strong name to the event handler assembly in Visual Studio

  1. With the TestEventHandler project open in Visual Studio, on the Project menu, click TestEventHandler Properties.

  2. On the project properties page, click the Signing tab.

  3. Select the Sign the assembly check box.

  4. In the Choose a strong name key file list, click New.

  5. In the Create Strong Name Key dialog box, type keyfile as the key file name, and then clear the Protect my key file with a password check box.

  6. Close the project properties page.

Adding the Code That Implements the Event Handler

To add the code that implements the event handler, use the following procedure.

To add the code

  1. Add the following Imports or using statements to the top of the PublishingEventHandler.cs or PublishingEventHandler.vb source file. For PublishingEventHandler.cs, add the using statements after the using statements that were generated by Visual Studio when the project was created.

    Imports System.Diagnostics
    Imports System.Net
    Imports System.Text
    Imports Microsoft.Office.Project.Server.Events
    Imports Microsoft.Office.Project.Server.Library
    Imports WSS = Microsoft.SharePoint
    
    using System.Diagnostics;
    using System.Net;
    using Microsoft.Office.Project.Server.Events;
    using Microsoft.Office.Project.Server.Library;
    using WSS = Microsoft.SharePoint;
    

    The Imports or using statements make it possible to use the classes and types defined in the referenced namespaces without needing to use fully qualified namespace paths.

  2. Add the code for the class that implements the event handler. The sample event handler writes an entry to the Application event log when a project publishing event occurs. Replace the Visual Studio–generated code for the PublishingEventHandler class with the following code.

    Public Class PublishingEventHandler
        Inherits ProjectEventReceiver
    
        Public Overrides Sub OnPublishing( _
            ByVal contextInfo As PSContextInfo, _
            ByVal e As ProjectPrePublishEventArgs)
    
            MyBase.OnPublishing(contextInfo, e)
    
    
            Dim myLog As EventLog = New EventLog()
            myLog.Source = "Project Server"
    
            ' Get information from the event arguments, and 
            ' write an entry to the Application event log. 
    
            Dim userName As String = contextInfo.UserName.ToString()
            Dim projectName As String = e.ProjectName.ToString()
            Dim siteGuid As Guid = contextInfo.SiteGuid
            Dim pwaUrl As String = New WSS.SPSite(siteGuid).Url
            Dim eventId As Integer = 7692
            Dim logEntry As String = String.Empty
    
            e.Cancel = False
    
            If (projectName.Substring(0, 3).Equals("Prj")) Then
                logEntry = vbCrLf + "User: " + userName + _
                    vbCrLf + "Project: " + projectName + _
                    vbCrLf + "Site ID: " + siteGuid.ToString() + _
                    vbCrLf + "PWA Instance: " + pwaUrl + _
                    vbCrLf + "The project name is valid. Publishing..."
    
                myLog.WriteEntry(logEntry, EventLogEntryType.Information, _
                        eventId)
            Else
                logEntry = vbCrLf + "User: " + userName + _
                vbCrLf + "Invalid project name: " + projectName + _
                vbCrLf + "Site ID: " + siteGuid.ToString() + _
                vbCrLf + "PWA Instance: " + pwaUrl + vbCrLf + _
                "To be published, the project name must start with " + _
                "'Prj'."
    
                myLog.WriteEntry(logEntry, EventLogEntryType.Warning, _
                    eventId)
    
                e.Cancel = True
                e.CancelReason = "Invalid Project Name."
            End If
        End Sub
    End Class
    
    public class PublishingEventHandler : ProjectEventReceiver
    {
        public override void  OnPublishing(PSContextInfo contextInfo,
            ProjectPrePublishEventArgs e)
        {
            base.OnPublishing(contextInfo, e);
    
    
            EventLog myLog = new EventLog();
            myLog.Source = "Project Server";
    
            // Get information from the event arguments, and 
            // write an entry to the Application event log. 
    
            string userName = contextInfo.UserName.ToString();    
            string projectName = e.ProjectName.ToString();
            Guid siteGuid = contextInfo.SiteGuid;
            string pwaUrl = new WSS.SPSite(siteGuid).Url;
            int eventId = 7692;
            string logEntry;
    
            e.Cancel = false;
    
            if (projectName.Substring(0, 3).Equals("Prj"))
            {
                logEntry = "\nUser: " + userName + 
                    "\nProject: " + projectName +
                    "\nSite ID: " + siteGuid.ToString() +
                    "\nPWA Instance: " + pwaUrl +
                    "\nThe project name is valid. Publishing...";
    
                myLog.WriteEntry(logEntry, EventLogEntryType.Information, 
                    eventId);
            }
            else
            {
                logEntry = "\nUser: " + userName + 
                "\nInvalid project name: " + projectName +
                "\nSite ID: " + siteGuid.ToString() +
                "\nPWA Instance: " + pwaUrl +
                "\nTo be published, the project name must start with " + 
                "'Prj'.";
    
                myLog.WriteEntry(logEntry, EventLogEntryType.Warning, 
                    eventId);
    
                e.Cancel = true;
                e.CancelReason = "Invalid Project Name.";
            }
        }
    }
    
  3. Build the TestEventHandler project.

Deploying the Event Handler

You can deploy the event handler assembly in two ways. On a computer running Office Project Server, either copy the assembly to a special event handler directory, or register the assembly in the global assembly cache.

To deploy the event handler

  • To copy the event handler assembly to the Office Project Server event handler directory, copy TestEventHandler.dll to the path %ProgramFiles%\Microsoft Office Servers\12.0\Bin\ProjectServerEventHandlers.

  • To register the TestEventHandler.dll assembly in the global assembly cache, either drag the assembly into the global assembly cache on the computer running Office Project Server, or use the gacgutil.exe tool that is included with Visual Studio. To open the global assembly cache, on the Windows Start menu, click Run, and then type assembly in the Run dialog box.

Registering the Event Handler in Project Server

Use the following procedure to register the event handler in Office Project Server through Project Web Access.

To register the event handler in Project Server

  1. In Project Web Access, in the left pane, click Server Settings.

    Figure 1. Server Settings page

    Server Settings page

  2. On the Server Settings page, in the Operational Policies section, click Server-Side Event Handler Configuration.

    Figure 2. Events page

    Events page

  3. On the Events page, in the Events list, click the Project link for the Publishing event. In the Event Handlers grid, click the New Event Handler link.

    Figure 3. Event Handler page

    Event Handler page

  4. On the Event Handler page, type the values shown in Table 1 for the various fields.

    Table 1. Values for Event Handler page fields

    Field

    Value

    Name

    Test Project Publishing Event Handler

    Description

    Value that ensures project names begin with "Prj"

    Assembly Name

    TestEventHandler,Version=1.0.0.0,Culture=Neutral,

    PublicKeyToken=PublicKeyTokenForTheAssembly

    Class Name

    TestEventHandler.PublishingEventHandler

    Order

    1

  5. Replace the PublicKeyTokenForTheAssembly placeholder in the Assembly Name field with the actual public key token of the assembly. You can use the strong name tool, sn.exe, to determine the public key token of the event handler assembly by doing the following:

    1. In Visual Studio, open a Command Prompt window.

    2. Navigate to the folder that contains the TestEventHandler.dll assembly, and then type the following command at the command prompt:

      sn -T TestEventHandler.dll

    The strong name tool displays the public key token of the assembly.

  6. Click Save to save the event handler settings.

    Office Project Server displays a message that explains that event registration is asynchronous and might take a few minutes to complete. Event registration uses the Shared Services Provider (SSP) and Windows SharePoint Services timer processes. If the timer interval is one minute, it can take up to two minutes to register the event handler with Office Project Server.

  7. Click OK to close the message box.

  8. Refresh the Events page to see the registered Project Publishing event handler displayed in the Event Handlers grid.

    Figure 4. Events page with registered event handler

    Events page with registered event handler

Testing the Event Handler

Use Project Web Access to test the project publishing event handler.

To use Project Web Access to test the project publishing event handler

  1. On the Project Web Access home page, in Quick Launch, under the Projects section, click Proposals and Activities.

  2. On the Proposals and Activities page, click New, and then click Proposal in the list.

  3. On the New Proposal page, complete the required information fields, ensuring that the proposal name does not start with "Prj", and then click Save.

  4. When saving is complete, click Save and Publish on the proposal page. Office Project Server attempts to publish the proposal.

  5. Open the Event Viewer on the computer running Office Project Server, click the Application events, and double-click the Warning event with the source of Project Server. The Event Properties dialog box appears showing information logged by the event handler.

    Figure 5. Event Properties dialog box

    Event Properties dialog box

    NoteNote

    The Proposals and Activities page in Project Web Access still shows the project. The Published field shows No and the information icon for the project shows it is a draft project. That is, Office Project Server saved the proposal only in the Draft database.

  6. To check the case where the name is correct, click the project name on the Proposals and Activities page, click Summary Information on the project details page, and then change the project name so that it begins with "Prj". Click Save and Publish; the project is published. The Event Viewer shows an Information event (instead of a Warning event) with the details logged by the event handler.

Debugging the Event Handler

Registered event handlers run on the Office Project Server computer and are called by the Project Server Eventing service. To debug an event handler, use Visual Studio 2005 and attach the debugger to the Project Server Eventing process.

To debug a Project Server event handler

  1. Register and test the event handler as described previously.

  2. If you are debugging from a remote computer, install and run the Microsoft Visual Studio Remote Debugging Monitor on the computer running Office Project Server.

  3. In Visual Studio, open the event handler project that you registered, and then on the Debug menu, click Attach to Process.

  4. In the Attach to Process dialog box, select the Default transport and browse to the name of the computer running Office Project Server for the Qualifier. Click Select, and then in the Attach to options, select only the Managed check box.

    Figure 6. Attach to Process dialog box

    Attach to Process dialog box

  5. Select both Show processes from all users and Show processes in all sessions.

  6. To put Visual Studio into debug mode, in the Available Processes list, click Microsoft.Office.Project.Server.Eventing.exe, and then click Attach.

  7. On the Tools menu, click Options. Expand the Debugging node in the options list, and then click Symbols. Click the folder icon and copy the TestEventHandler project debug build directory path in the new symbol file location. Select Load symbols using the updated settings when this dialog is closed to load the TestEventHandler.pdb symbol file, and then click OK.

  8. In the code window for PublishingEventHandler.cs or PublishingEventHandler.vb, place a breakpoint at the beginning of the OnPublishing method. If the breakpoint shows only a red outline with a yellow warning symbol, the TestEventHandler.pdb symbol file is not loaded.

  9. Trigger the Publishing event by publishing a project, and step through the OnPublishing event handler in Visual Studio.

  10. Debugging cannot work if the event handler code is changed and recompiled after registering the event handler with Office Project Server. If the event handler is recompiled, you must re-register it by using the following steps:

    1. Unregister the event handler in Office Project Server.

    2. Remove the old event handler assembly from the global assembly cache or delete it from the path %ProgramFiles%\Microsoft Office Servers\12.0\Bin\ProjectServerEventHandlers.

    3. Register the recompiled event handler in the global assembly cache, or copy it to the %ProgramFiles%\Microsoft Office Servers\12.0\Bin\ProjectServerEventHandlers path.

    4. Re-register the event handler in Office Project Server.

Read It

This article shows how to write and debug event handlers for Project Server 2007. The key steps include:

  1. Creating a Class Library project in Visual Studio 2005.

  2. Adding references to the required assemblies to the Visual Studio project.

  3. Signing the class library assembly with a strong name.

  4. Adding the code that implements an event handler for the project publishing event.

  5. Deploying the event handler assembly to the computer running Office Project Server.

  6. Registering the event handler with Office Project Server through Project Web Access.

  7. Testing the event handler.

  8. Debugging the event handler.

Explore It