Cause and Effect

Working with Event Handlers in MOSS 2007





Cause and Effect

Working with Event Handlers in MOSS 2007


By Vikram Srivatsa


SharePoint 2007 features improvements over its predecessor in many areas, including document management, search, collaboration, etc. This article explores the enhancements made in the area of event handling and looks at the use of event handlers in SharePoint-based solutions.


Scenarios for Event Handlers

Event handlers provide a mechanism to extend the functionality of SharePoint and perform custom tasks based on specific actions performed by the user. For example, when a user is uploading a new document to a document library and the business wants to impose a specific naming convention for files uploaded by each user. In this situation, an event handler would allow us to validate the document name making use of the corresponding event for this action, and either reject the upload operation (informing the user to make the changes) or automatically rename it based on naming conventions defined.


Some other scenarios in which event handlers would be suitable are listed here:

  • Send a custom e-mail message to a specific set of users when a comment is posted to a Discussion Board.
  • Prevent a List entry from being deleted based on specific business rules.
  • Automatically fill in additional data from other sources, such as the Enterprise Directory or a Web service, based on the current user. For example, the e-mail address or phone number of the user.
  • Perform an action that requires a higher privilege by impersonating an administrator. For example, to update an Item in a second list where the current user does not have permissions based on the updates on the first list where the user does have permissions.


SharePoint itself harnesses events internally to provide the audit features.


Event Handler Enhancements in MOSS 2007

Now that we ve looked at the usage scenarios for event handlers, let s look at the enhancements provided as part of the new version of SharePoint.


Event handlers were available as part of SharePoint Portal Server 2003 (SPS2003), but the event handlers in SPS2003 were restricted to document libraries. This restriction was a major limitation, as it was not possible to manage events on any of the other data stores provided by SharePoint, such as Lists, Discussion Boards, or Surveys.


MOSS 2007 adds to these other elements event handling capabilities in a consistent manner, and also provides certain additional events that can be captured at the List level and the Site/Site Collection level, apart from the Item-level events.


Event Types

As mentioned, the event handlers can be classified into three main types: Item, List, and Site/Site Collection.


Each EventReceiver class exposes two types of events for each event: a Before event and an After event. The Before event occurs before an action has been completed; it is synchronous. Hence, within the Before event it is possible to cancel the action being performed. The After event occurs after the completion of the action. The After event is asynchronous. There is a consistent naming pattern followed for Before and After events. The name of a Before event always ends with ing, such as WebDeleting, ItemAdding, etc. Similarly, an After event always ends with ed, such as WebDeleted, ItemAdded, etc.


Corresponding to this classification, the SharePoint Object Model provides three separate EventReceiver classes to manage the respective events:

  • SPWebEventReceiver. This enables trapping events fired at the Site and Site Collection level. The Events supported are the Before and After events for the deletion of a site or a site collection.
  • SPListEventReceiver. This enables trapping events fired at the List level, such as addition, modification, and deletion of fields in a List.
  • SPItemEventReceiver. This enables trapping events fired at the Item level, such as addition, modification, deletion, check in, check out, etc.


The classification and functionality offered by each of these EventReceiver classes is summarized in Figure 1.


Figure 1: SharePoint 2007 EventReceiver classes.


I will not be discussing each of the specific events provided by these event receivers. For detailed information on which events are provided, please refer to the URLs provided in Figure 2.


Event Type

MSDN Reference URL




Figure 2: Event handler reference links.


Each event handler method accepts an event properties class as a parameter. This parameter provides access to useful properties for the specific event. Some of the properties available as part of this event parameter are listed in Figure 3.


Event Property



Refers to the instance of the current Web where the event occurred.


Refers to the instance of the current List where the event occurred for List-level and Item-level events.


Refers to the instance of the current Item on which the event occurred.


Gets the type of event that occurred on the Item, List, or Site.


Refers to the LoginName of the current user who caused the event to occur.


Refers to the DisplayName of the current user who caused the event to occur.


This property can be used in Before events to cancel the event from completing.


This property provides a mechanism for the user to interact with the current user by displaying an error message.

Figure 3: Event properties.


Building an Event Handler

Let s now look at building an event handler one that will be useful in the following scenario.


The Site-level permissions provided by SharePoint 2007 are not granular enough to meet specific business requirements on many occasions. For example, it is necessary to grant the Manage Web Site permission to a certain role, to enable the role to perform Web site management but not necessarily the ability to delete the Web site. The default Manage Web Site permission includes the rights to delete a Web site, so the issue of granularity arises if the business rules do not want this role to be able to delete the Web site. For more information on permission levels of SharePoint 2007, please refer to the following URL:


To meet this specific business need, it is possible to create a Site-level event handler that verifies the role assigned to the current user and prevents the user from deleting the Web site. The EventReceiver classes are not directly instantiated, but a class that inherits from the EventReceiver class is used and the corresponding methods of the base class are overridden to provide the custom functionality required.


Because we wish to prevent the completion of the event if the validation fails, we need to use the Before event provided for the site. The actual Before event in this case would be the WebDeleting event.


Let s now understand the code snippet that needs to be used to enable this functionality (see Figure 4). This code snippet needs to be built as part of a Class Library using Visual Studio 2005. Using the event properties it is possible to retrieve the current SPWeb instance. The SPWeb instance has a property named AllRolesForCurrentUser, which is a collection of all roles for the current user (this is illustrated on line 6 in Figure 4).


Figure 4: Event handler sample code listing.


The code iterates through all the roles assigned to the user and allows the user to delete the site only if the user has the Full Control role assigned to him/her (this is illustrated on line 9 in Figure 4).


If the user is not found to have the Full Control role assigned, the Cancel property on the event argument is set to true. The event argument also exposes a property named Message, which provides a mechanism to display an error message back to the user (these steps are illustrated on line 18 in Figure 4). This is illustrated in Figure 5.


Figure 5: Error message shown to user.


NOTE: The assembly containing the derived EventReceiver class must be strongly named and deployed in the Global Assembly Cache.


Enabling Event Handlers

Event handlers must be enabled at the WebApplication level for the events to trigger. There is limited support in terms of a user interface for configuring and managing event handlers.


The event handlers need to be enabled in code. The code snippet for enabling the event handler on a Web application is shown in Figure 6.


SPSite objSite = new SPSite("SiteUrl");

if (!objSite.WebApplication.EventHandlersEnabled) {

     objSite.WebApplication.EventHandlersEnabled = true;

     objSite.WebApplication.Update(); }

Figure 6: Enabling event handlers.


Registering the Event Handler

Event handlers can be deployed as Features that can be activated. Having an event handler as a Feature makes the deployment easier as the scope of a Feature can be specified at the farm level, thus ensuring that the event handler has been applied to all existing elements on the farm. A more detailed discussion covering Features is beyond the scope of this article; for more information please refer to WSS and MOSS.


Event handlers also can be registered in code by using the SharePoint Object Model and adding the event to either the Site or the List. The code snippet for registering the DeletionController class discussed in the previous section is shown in Figure 7.


Figure 7: Event handler registration.


The SPWeb object holds the EventReceiver collection to which the event handler details need to be added. The Add method accepts the event being registered, which in this case is the WebDeleting event. The next parameter accepts details of the strongly named assembly, which contains the event handler; the final parameter accepts the name of the derived EventReceiver class, which in the sample discussed is WebDeleteController.DeletionController.


The drawback of the code-based approach in this case is the fact that we would need to register the event with every site by crawling through all the existing sites. This is cumbersome. The code-based approach would probably be more useful in scenarios where the site itself is being created programmatically, in which case it would be possible to register the event at the time of site creation.


There is also an event handler management UI built as an extension on the Microsoft CodePlex site, which can be accessed from


Support for SPS2003 Event Handlers

I mentioned in the beginning of this article that SPS2003 supported events for document libraries. In case you have event handlers from SPS2003 that you want to leverage in a SharePoint 2007 library, this can be achieved. SharePoint 2007 provides backward compatibility for event handlers written for SPS2003.


However, this is an explicit setting that needs to be enabled at the Web Application level in Central Administration (Application Management | Web Application General Settings | Backward-Compatible Event Handlers). This is accessible at servername:port/_admin/vsgeneralsettings.aspx. This setting is illustrated in Figure 8.

Figure 8: Backward-compatible event handlers settings.


Enabling this option will allow the use of SPS2003 event handlers in MOSS 2007. The specific event handler information would need to be specified in the document library s Advanced settings.



This article explored the concept of event handlers with MOSS 2007, and introduced some typical scenarios where event handlers would prove to be useful. It also covered the development of a custom event handler for the WebDeleting event on a site.


Vikram Srivatsa is a Technology Consultant at HP Services and works out of Bangalore, India.




Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.