Event Receivers in SharePoint

1. Introduction

While developing any application we need to handle some events. For example, when a new item is added to a list, we may need to perform some action like say, notifying the person who created the list item, or modifying the dependent entries in some other location etc. Handling of such events is facilitated by event receivers. We have many SharePoint event receiver classes in order to handle variety of events.

2. SharePoint Event Receiver types

There are basically two types of event receivers: Synchronous and Asynchronous event receivers.Synchronous event receivers are also known as ‘Before’ event receivers. They are used to perform some custom action before an event occurs. In this case, there is a flexibility of cancelling the event on some conditions so that the event that gets initiated will not occur.
Asynchronous event receivers are also known as ‘After’ event receivers. They are used to perform some custom action after an event occurs. These events are asynchronous because they need not happen immediately after the event is performed. They can happen sometime later also, unlike synchronous event receivers which occur immediately before an event occurs.

3. Classes of Event Receivers

There are fundamentally five classes for Event Receivers for SharePoint 2007.
Microsoft.SharePoint.SPEmailEventReceiver : This provides event handling whenever a user sends an email to a list on which e-mail feature is enabled
Microsoft.SharePoint.SPFeatureReceiver : This provides event handling whenever is feature is acted upon
Microsoft.SharePoint.SPItemEventReceiver : This provides event handling whenever any action is performed on a list item
Microsoft.SharePoint.SPListEventReceiver : This provides event handling whenever a list definition is modified like adding or deleting columns and modifying existing columns.
Microsoft.SharePoint.SPWebEventReceiver : This provides event handling whenever a site or a site collection is deleted or moved
Each of the classes has some virtual methods which are to be over-ridden to perform our custom action. Those methods are as follows.

3.1 Site Level Events

Methods under the class SPWebEventReceiver handle site level events. A brief overview of those methods is as follows.
Site Deleted - This occurs after a site collection is deleted.
Site Deleting - This occurs before a site collection is being deleted.
Web Deleted - This occurs after a website has been deleted completely. This is an asynchronous after event.
Web Deleting - This occurs before a website is deleted. This is a synchronous before event.
Web Moved - This occurs after an existing website is moved. This is an asynchronous after event.
Web Moving - This occurs before a website is moved. This is a synchronous event.

3.2 List Level Events

Methods under the class SPListEventReceiver handle list level events. A brief overview of those methods is as follows.
Field Added - This occurs after a field link is added to a list.
Field Adding - This occurs when is field is being added to a content type.
Field Deleted - This occurs after a field is deleted from a list.
Field Deleting - This occurs when a field is being deleted from a list.
Field Updated - This occurs after a field is updated in a list.
Field Updating - This occurs when a field is being updated in a list.

3.3 Item Level Events

Methods under the class SPItemEventReceiver handle item level events. A brief overview of those methods is as follows.
ItemAdded - This occurs after a new item is added to a list. This is an asynchronous after event.
ItemAdding - This occurs before an item is added to a list. This is a synchronous before event.
ItemAttachmentAdded - This occurs after an attachment is added to a list. This is an asynchronous event.
ItemAttachmentAdding - This occurs while an attachment is being added to a list.
ItemAttachmentDeleted - This occurs after an attachment is removed from an item.
ItemAttachmentDeleting - This occurs while an attachment is being removed from an item.
ItemCheckedIn - This occurs after an item is checked in.
ItemCheckedOut - This occurs after an item is checked out.
ItemCheckingIn - This occurs while an item is being checked in.
ItemCheckingOut - This occurs while an item is being checked out.
ItemDeleted - This occurs after an item is deleted from its list.
ItemDeleting - This occurs while an item is being deleted from its list.
ItemFileConverted - This occurs when the type of file is being converted.
ItemFileMoved - This occurs after a file is moved.
ItemFileMoving - This occurs while a file is being moved.
ItemUncheckedOut - This occurs after un-checking an item in a list.
ItemUncheckingOut - This occurs while an item is being unchecked.
ItemUpdated - This occurs after an item is updated.
ItemUpdating - This occurs while an item is being updated.

3.4 Feature Events

Methods under the class SPFeatureReceiver handle events related to feature. A brief overview of those methods is as follows.
FeatureActivated - This occurs after a feature is activated.
FeatureDeactivating - This occurs when a feature is being deactivated.
FeatureInstalled - This occurs after a feature is installed.
FeatureUninstalling - This occurs when a feature is being uninstalled.

3.5 Email Events

Method under the class SPEmailEmailEventReceiver handles the event related to email. A brief overview of the method is as follows.
EmailReceived This occurs after an email message has arrived (to an email enabled list).

4. Binding the Event Receivers

For the event receivers to receive an event, they should be bound to the corresponding objects. This binding can be done in three ways.
Using a feature
Using a content type
Using WSS object model

4.1 Using Feature

In the feature, the elements.xml file should be as follows.
<Elements xmlns=”http://schemas.microsoft.com/sharepoint/“>
……………………
……………………
<Receivers ListTemplateId=”100″>
< Receiver>
< Name>VideoAddedEventReceiver</Name>
< Type>ItemAdded</Type>
< SequenceNumber>20000</SequenceNumber>
< Assembly>MyProject.MyModule.Events, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0b231a5ff63cd9fa</Assembly>
< Class>MyProject.MyModule.Events.VideoAddedEventReceiver</Class>
< Data></Data>
< Filter></Filter>
< /Receiver>
………………………………
……………………………..
< /Receivers>
< /Elements>
Any number of receivers can be bound through one feature.
Limitation: Site level events cannot be registered/bound through the feature because we cannot associate a ListTemplateId with a site.

4.2 Using Content Type

In a content type, the elements.xml file should be as follows.
<Elements xmlns=”http://schemas.microsoft.com/sharepoint/“>
<ContentType ID=”id” Name=”name” Group=”GroupName” Description=”Description of content type” Version=”0″>
< FieldRefs>
< FieldRef ID=”FIELD ID” Name=”FIELD NAME” />
…………………………
…………………………
< /FieldRefs>
< XmlDocuments>
< XmlDocument NamespaceURI=”http://schemas.microsoft.com/sharepoint/events“>
<spe:Receivers xmlns:spe=”http://schemas.microsoft.com/sharepoint/events“>
<Receiver>
< Name> VideoAddedEventReceiver </Name>
< Type> ItemAdded </Type>
< SequenceNumber>20000</SequenceNumber>
< Assembly> MyProject.MyModule.Events, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0b231a5ff63cd9fa </Assembly>
< Class> MyProject.MyModule.Events.VideoAddedEventReceiver</Class>
< Data></Data>
< Filter></Filter>
< /Receiver>
< /spe:Receivers>
< /XmlDocument>
< /XmlDocuments>
< /ContentType>
< /Elements>
The same limitation of ‘using feature’ applies to content type also because a content type cannot be associated with a site.
Sequence Number determines when the event receiver should get executed in case if more than one event receivers are about to be executed. An event receiver with greater sequence number gets executed after its counterpart with lesser sequence number.

4.3 Using WSS object model

The below is a sample code how an event receiver is bound with a list.
public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
SPWeb web = properties.Feature.Parent as SPWeb;
web.Lists["Video Library"].EventReceivers.Add(
SPEventReceiverType.ItemAdded,
“MyProject.MyModule.Events, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0b231a5ff63cd9fa”,
” MyProject.MyModule.Events.VideoAddedEventReceiver “);
}
In the above code, the custom class ‘VideoAddedEventReceiver’ of type ‘ItemAdded’ is bound with a list named ‘Video Library’.

5. Unbinding SharePoint Event Receiver

• Event receiver bound with the help of content type cannot be unbound.
• If the event receiver was bound with the help of a feature, deactivating the feature would unbind the event receiver from its associated object.
• If the event receiver was bound using WSS object model,
1. Move to the object (site collection or website or list) to which the event receiver is bound.
2. Retrieve the event receiver definition of the intended event receiver.
3. EventReceiverDefinitionObject.Delete().
4. Call the update of that object (site collection or website or list).