Creating a Basic Event Handler

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The following example shows the basic steps of creating an event handler that executes code before a list item is deleted or after an item is added. The example works on announcement lists, adding text to the body of new items, but cancelling attempts to delete existing items.

You create an event handler assembly in Microsoft Visual Studio 2005 by creating a class library. You add the reference to Microsoft.SharePoint.dll and inherit from the Microsoft.SharePoint.SPItemEventReceiver base class, as shown in the following example.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;

namespace MyEventHandlers

{
    public class SimpleEventHandler : SPItemEventReceiver
    {
    }
}

Windows SharePoint Services 3.0 instantiates an object of your class when actions occur within the list. As a developer, you override the methods of the SharePoint base class for the events you are interested in handling. The methods of the SPItemEventReceiver class that you can override are the following:

The example overrides two methods: ItemDeleting and ItemAdded. Remember that the suffix "ing" indicates that we are handling the event in a synchronous way before the action actually occurs, and the suffix "ed" indicates that we are handling the event in an asynchronous way after the action occurs.

public override void ItemDeleting(SPItemEventProperties properties)
{
    properties.Cancel = true;
    properties.ErrorMessage = "Deleting is not supported.";
}

You have access to the data associated with the SPListItem object through an object that is provided as an input parameter when your method is called. This object is of type SPItemEventProperties. Through the Cancel property of the SPEventPropertiesBase class you can cancel the event, and through the ErrorMessage property you can display a custom error message on a SharePoint page.

The second method to override is ItemAdded. The following example uses the ListItem property to return an object that represents the new list item, and then modifies the body text of the item.

public override void ItemAdded(SPItemEventProperties properties)
{
    SPListItem oItem = properties.ListItem;
    oItem["Body"] = "Body text maintained by the system.";
    oItem.Update();
}

You must register both the ItemDeleting and ItemAdded event receivers as described in Registering an Event Handler.

Creating a Basic Event Handler

See Also

Tasks

Concepts

Additional resources