SharePoint Event Receivers

In SharePoint you can add event handlers to the different lists, document libraries and content types within a SharePoint site. Event handlers are defined in custom .NET assemblies. You can define event handlers for the different operations on list items, like adding a list item, updating a list item or deleting a list item.

Event handlers need to be registered and can best be installed and registered through the SharePoint feature framework.

Synchronous and Asynchronous Events

There are synchronous and asynchronous events. Events ending by –ing are synchronous events: ItemAdding, ItemUpdating, ItemDeleting. Event handlers defined for these events are executed before the operation is executed on the content database. Asynchronous events are the events that end by –ed: ItemAdded, ItemUpdated, ItemDeleted. Event handlers for these events are executed after the operation is occurs in the content database.

Base Classes

There are different base classes from which you can inherit when developing event handlers. The decision from which class you are going to inherit depends on what you want to achieve with your event handler:

•  SPItemEventReceiver: inherit from this class if you want your event handler to be executed when a list item is added, updated or deleted.
•  SPListEventReceiver: inherit from this class if you want your event handler to be executed when the structure of your list is modified or when a content type is added or removed from the list.
•  SPFeatureEventReceiver: you can add an event handlers to a feature events like activation and deactivation, installation and deinstallation.
•  SPEmailEventReceiver: you can also develop an event handler for emails that are sent to a SharePoint list.

•  SPWebEventReceiver: you can also handle events that occur when a site is added to or removed from a site collection.

Updating the list item

There are 3 methods to update a list item:

• Update: With this method you can update the list item. But it also changes the Modified By column (internal name Editor) to the SHAREPOINT\system account and sets the Modified column to the current date time. If versioning is enabled, the version is increased.
• SystemUpdate: This method also updates the list item but preserves the values in the Modified By column (internal name Editor) and the Modified column. This method comes with two overloads. You can also specify a boolean value to indicate if you want to increase the version number or not.

 

·         UpdateOverwriteVersion: This method updates the list item without changing the version number. It also allows to modifiy the values in the system columns lik Created By (internal name Author), Modified By (internal name Editor), Modified and Created.

Disabling and Enabling the event handler

To avoid that a list item event handler is triggered again and again and again, you have to prevent the event handler from firing before you update changes to the list item. You can achieve this by executing the DisableEventFiring method on the list item. After the changes are saved you can activate the event handler again by executing the EnableEventFiring method on the list item.

Best practice is to execute the DisableEventFiring method right before any of the update methods and to execute the EnableEventFiring method right after one of the update methods. 

AllowUnsafeUpdate

AllowUnsafeUpdate is a property on the SPSite and SPWeb objects. You can set it to true to avoid security validation before the changes are written to the content database. There is an excellent and very detailed post about this property.

RunWithElevatedPermissions

You will find a lot of code snippets wrapped in a RunWithElevatedPermissions construct. This is necessary if you will be changing data that is not accessible by some types of users. For example if you need to update a column or another list when a document or list item is read, this will cause en error when the user has only read access to this list or the other list. In that case you can wrap your update code in the following construct:

SPSecurity.RunWithElevatedPrivileges(delegate()
{
    using (SPWeb web = properties.OpenWeb())
    {

      // web will be based on the rights for the system account
     // here follows your event handler code

    }

});