Share via


Example: Creating a List Item Event Handler

Applies to: SharePoint Foundation 2010

The following example shows the basic steps used to create an event handler. In this example, the event handler 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 and cancelling attempts to delete existing items.

You create an event handler assembly in Microsoft Visual Studio by creating a class library. Add a 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
    {
    }
}
Imports System
Imports System.Collections.Generic
Imports System.Text
Imports Microsoft.SharePoint

Namespace MyEventHandlers

    Public Class SimpleEventHandler
        Inherits SPItemEventReceiver
    End Class
End Namespace

An object of your class is instantiated when actions occur within the list. As a developer, you override the methods of the base class for the events you are interested in handling. The methods of the SPItemEventReceiver base class that you can override include the following:

The example overrides two methods: ItemDeleting and ItemAdded. Remember that the suffix "-ing" indicates that the event is being handled before the action occurs, and the suffix "-ed" indicates that the event is being handled after the action occurs.

public override void ItemDeleting(SPItemEventProperties properties)
{
    properties.Cancel = true;
    properties.ErrorMessage = "Deleting is not supported.";
}
Public Overrides Sub ItemDeleting(ByVal properties As SPItemEventProperties)
        properties.Cancel = True
        properties.ErrorMessage = "Deleting is not supported."
End Sub

Data that is associated with the list item is contained in the ListItem property. You can access these property values by using the AfterProperties property bag.

The second method that you must 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();
}
Public Overrides Sub ItemAdded(ByVal properties As SPItemEventProperties)
    Dim oItem As SPListItem = properties.ListItem
    oItem("Body") = "Body text maintained by the system."
    oItem.Update()
End Sub

You must register both the ItemDeleting and ItemAdded event receivers, as described in Binding a SharePoint Foundation Event Handler.

See Also

Tasks

How to: Create an Event Handler Feature

Concepts

Binding a SharePoint Foundation Event Handler

Event Registrations

Security Validation and Making Posts to Update Data

Elevation of Privilege

Using Features in SharePoint Foundation