This documentation is archived and is not being maintained.

SPEventReceiverDefinition Class

Windows SharePoint Services 3

Abstract base class that defines general properties of an event receiver that will reside in the SPEventReceiverDefinitionCollection.


Namespace:  Microsoft.SharePoint
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)

[SharePointPermissionAttribute(SecurityAction.LinkDemand, ObjectModel = true)]
[SharePointPermissionAttribute(SecurityAction.InheritanceDemand, ObjectModel = true)]
public sealed class SPEventReceiverDefinition

An event receiver is a piece of managed code that responds to Windows SharePoint Services events whenever specific triggering actions occur. Triggering Windows SharePoint Services objects include list items, lists or document libraries. Triggering actions include activities such as adding, moving, and checkout. Objects that expect to receive events are event hosts, which are objects like site collections, sites, lists, list items, workflows, or features. For example, adding an list item to a list implies that the item to be added must be sent via an event to the event receiver, which sends a request to the event host to add the item to the list and then signal the originating job thread when the add operation is complete.

Windows SharePoint Services events are separated into two categories: "Before" events and "After" events. In Windows SharePoint Services, "before" events are named "" and "after" events are named "...ed".

"Before events" fire in response to a user action that occurs before Windows SharePoint Services writes data back to the content database. They allow an implementation to perform security checks and custom validation, so they occur early in the request processing lifecycle to support cancellation of the user action. All "before" event receivers are synchronous, and they block the flow of job thread execution until the event handler completes.

"After" events have event handlers that execute after Windows SharePoint Services commits the user action by writing data back to the content database. "After" events do not support cancellation of the user action. Instead, they start custom processing logic that runs whenever content has been modified.

There are two types of event processing that can occur when an "after" event is raised: synchronous and asynchronous. Synchronous processing provides the ability to cancel an event, so no “…ed” method is necessary. Asynchronous event receivers are processed by a separate thread, so processing does not block the flow of code execution. The separate job thread for asynchronous processing is started by methods that reside in namespaces other than the SPEventReceiverDefinition namespace. The other namespace also contains a method named "...ed" that will execute after the activities associated with the event complete execution, terminate with an exception, or are cancelled.

Event receivers are registered on the Windows SharePoint Services server that is associated with event host processes and that listens for the events that will be sent to it. Use the EventReceivers property of the SPContentType, SPFile, SPList, SPListItem, SPWeb, or SPWorkflow class to register the SPEventReceiverDefinitionCollection for the given Windows SharePoint Services object.

Use an indexer to return a single event receiver definition from the SPEventReceiverDefinitionCollection. For example, if the collection is assigned to a variable named collEventReceiverDefinitions, use collEventReceiverDefinitions[index] in C#, or collEventReceiverDefinitions(index) in Visual Basic .NET, where index is either the index number of the definition in the collection or the Guid of the definition.

The following example uses members of the SPEventReceiverDefinition class to register an ItemAdding(SPItemEventProperties) event receiver for the Contacts list of a specified Web site.

string listName = "Contacts";
string siteURL = "http://Server/Site";
string receiverName = "Contacts Event Receiver";
int sequenceNumber = 2001;
string assemblyFullName = "Assembly_Name, Version=1.0.1777.23493, Culture=neutral, PublicKeyToken=94de0004b6e3fcc5";
string assemblyClassName = "Assembly_Name.Class_Name";

SPList list = new SPSite(siteURL).OpenWeb().Lists[listName];
SPEventReceiverDefinitionCollection eventReceivers = list.EventReceivers;

SPEventReceiverDefinition eventReceiver = eventReceivers.Add();
eventReceiver.Name = receiverName ;
eventReceiver.Type = SPEventReceiverType.ItemAdding;
eventReceiver.SequenceNumber = sequenceNumber; 
eventReceiver.Assembly = assemblyFullName ;
eventReceiver.Class = assemblyClassName ;
eventReceiver.Synchronization = SPEventReceiverSynchronization.Synchronous;


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.