Item- and List-Level Event Receivers

To interact with lists and items, you can attach event receivers. With these your code is called when a specified condition is met in the attached list. The implementation uses the SPListItemEventReceiver base class—you simply override the methods you want to activate.

Synchronous vs. Asynchronous Events

SharePoint is rich with the events it exposes. We can categorize SharePoint events in two ways: by the “level” that fires the event (site, list, item) and by the type of the event (synchronous or asynchronous).

WHAT SYNCHRONOUS/ASYNCHRONOUS MEANS FOR EVENTS?

Synchronous events happen “before” the actual event. You have the HttpContext; you can display an error message in the browser, and if needed, you can cancel the event before it occurs.
Asynchronous events happen “after” the actual event. There is no HttpContext; you cannot directly show an error message, and you cannot cancel the event. On the other hand, you can handle what happens after the event is fired, including manipulating the object.
As examples of synchronous and asynchronous events, consider item-level events such as ItemAdding and ItemAdded. With ItemAdding, you can inspect the item, and, if necessary, cancel the addition and display an error message in the SharePoint page to the user. Inside the ItemAdded event, however, you know that the item is already in the SharePoint list, but you can start some post-add actions concerning that item.

Synchronous events are also called “before” events. They appear before the internal operation occurs. The event handler is also blocking the current flow. For this reason, we recommend you avoid time-consuming operations here.

Event Description
ItemAdding Occurs when a new item is added to its containing object
ItemAttachmentAdding Occurs when a user adds an attachment to an item
ItemAttachmentDeleting Occurs when a user removes an attachment from an item
ItemCheckingIn Occurs as a file is being checked in
ItemCheckingOut Occurs before an item is checked out
ItemDeleting Occurs before an existing item is completely deleted
ItemFileMoving Occurs when a file is being moved
ItemUncheckedOut Occurs before an item is being unchecked out
ItemUpdating Occurs when an existing item is changed, for example, when the user changes data in one or more fields
Asynchronous events are classified as “after” events. They are called asynchronously. Lengthy operations do not block the current thread. Because the internal operation is completed, you can safely manipulate the freshly added or changed data.
Event Description
ItemAdded Occurs after a new item has been added to its containing object
ItemAttachmentAdded Occurs after a user adds an attachment to an item
ItemAttachmentDeleted Occurs after a user removes an attachment from an item
ItemCheckedIn Occurs after an item is checked in
ItemCheckedOut Occurs after an item is checked out
ItemDeleted Occurs after an existing item is completely deleted
ItemFileMoved Occurs after a file is moved
ItemUncheckingOut Occurs after an item is unchecked out
ItemFileConverted Occurs after a file has been converted
ItemUpdated Occurs after an existing item is changed, for example, when the user changes data in one or more fields
List Events

List events (see below) occur for list operations that affect the whole list, such as schema changes. As for the list item events, you can choose synchronous and asynchronous events. The implementation uses the SPListEventReceiver base class—you simply override the appropriate methods.

Synchronous List-Level Events are shown next:

Event Description
FieldAdding Occurs when a field link is being added to a content type
FieldDeleting Occurs when a field is being removed from the list
FieldUpdating Occurs when a field link is being updated

Asynchronous List-Level Events are similar:
Event Description
FieldAdded Occurs after a field link is added
FieldDeleted Occurs after a field has been removed from the list
FieldUpdated Occurs after a field link has been updated

Developing and Deploying an Event Receiver

This section contains a step-by-step guide to developing event receivers and attaching them to the appropriate objects. In this example, we will create a simple receiver, which will handle two asynchronous events (ItemAdded and ItemUpdated) in all Document and Picture libraries at a SharePoint web site, and deploy it as a feature at the site level. The templates Visual Studio 2010 provides for this adds the required configuration files. The template comes with a wizard that asks for the particular event you want to create. Therefore, there is just one template for all possible events.



The wizard asks for the SharePoint site and whether the solution is a sandboxed or farm solution. Next you can select the type of event (List, List Item, and so on) and what specific event handler the wizard should create.

The wizard creates the package (solution), the feature that activates and deactivates the event handlers, and the event handler definition. An event handler definition consists of an Element.xml file that defines events, where they attach and the entry point of the assembly that contains the code:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Receivers ListTemplateId="104">
<Receiver>
<Name>EventReceiver1ItemAdded</Name>
<Type>ItemAdded</Type>
<Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
<Class>ItemEventReceiverProject.EventReceiver1.EventReceiver1</Class>
<SequenceNumber>10000</SequenceNumber>
</Receiver>
<Receiver>
<Name>EventReceiver1ItemUpdated</Name>
<Type>ItemUpdated</Type>
<Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
<Class>ItemEventReceiverProject.EventReceiver1.EventReceiver1</Class>
<SequenceNumber>10000</SequenceNumber>
</Receiver>
</Receivers>
</Elements>

The Event Handler Code

The code snippet created by the wizard (see Listing 4-14) attaches the two events to their event handlers. This is shown “as is.” No changes were made to fix namespaces or anything else.

using System;
using System.Security.Permissions;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Security;
using Microsoft.SharePoint.Utilities;
using Microsoft.SharePoint.Workflow;

namespace Apress.SP2010.EventReceiver1
{
/// <summary>
/// List Item Events
/// </summary>
public class EventReceiver1 : SPItemEventReceiver
{
/// <summary>
/// An item is being added.
/// </summary>
public override void ItemAdded(SPItemEventProperties properties)
{
base.ItemAdded(properties);
}

/// <summary>
/// An item is being updated.
/// </summary>
public override void ItemUpdated(SPItemEventProperties properties)
{
base.ItemUpdated(properties);
}

}
}

The receiver class must inherit from SPItemEventReceiver. To attach other events, you can override the corresponding methods in this class and extend the Elements.xml to connect the handler with the event source.