SPEventReceiverDefinition Class

Abstract base class that defines general properties of an event receiver for list items, lists, websites, and workflows.

Namespace:  Microsoft.SharePoint
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online

<SubsetCallableTypeAttribute> _
Public NotInheritable Class SPEventReceiverDefinition _
	Inherits SPAutoSerializingObject
Dim instance As SPEventReceiverDefinition

An event receiver is managed code that responds to SharePoint Foundation events whenever specific triggering actions occur. Triggering SharePoint Foundation objects include list items, lists, or document libraries. Triggering actions include activities such as adding, moving, or checkout. Objects that expect to receive events are event hosts, which are objects like site collections, sites, lists, workflows, or features. SharePoint Foundation events are separated into two categories: Before events and After events. In SharePoint Foundation, Before events are named "...ing" and After events are named "...ed". Before events fire in response to a user action that occurs before SharePoint Foundation 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 SharePoint Foundation commits the user action by writing data back to the content database. After events do not support cancellation of the user action. 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 run the event in the same thread before sending the Web response back to the browser. 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 classes other than the SPEventReceiverDefinition class.

Use the EventReceivers property of the SPContentType, SPFile, SPList, SPSite, SPWeb, or SPWorkflow class to get the collection of event receivers registered for the given Microsoft SharePoint Foundation object. Once you have a reference to the event receiver collection (of type SPEventReceiverDefinitionCollection), you can use it to add a new event receiver definition or retrieve an existing one. Use the Add() method to create a new event SPEventReceiverDefinition object. Then set the different properties that make up the definition, and call the Update() method to save the event receiver definition.

Use an indexer to return a single event receiver definition from the collection. 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 a synchronous ItemAdding event receiver for the Contacts list of a specified Web site.

Dim listName As String = "Contacts"
Dim siteURL As String = "http://Server/Site"
Dim receiverName As String = "Contacts Event Receiver"
Dim sequenceNumber As Integer = 2001
Dim assemblyFullName As String = "Assembly_Name, Version=1.0.1777.23493, Culture=neutral, PublicKeyToken=94de0004b6e3fcc5"
Dim assemblyClassName As String = "Assembly_Name.Class_Name"
Dim receiverData As String = "Data"

Dim list As SPList = New SPSite(siteURL).OpenWeb().Lists(listName)
Dim eventReceivers As SPEventReceiverDefinitionCollection = list.EventReceivers

Using site As New SPSite(siteURL)
   Using web As SPWeb = site.OpenWeb()
     Dim list As SPList = New SPSite(siteURL).OpenWeb().Lists(listName)
     Dim eventReceivers As SPEventReceiverDefinitionCollection = list.EventReceivers

     Dim eventReceiver As SPEventReceiverDefinition = eventReceivers.Add()
     eventReceiver.Name = receiverName
     eventReceiver.Synchronization = SPEventReceiverSynchronization.Synchronous
     eventReceiver.Type = SPEventReceiverType.ItemAdded
     eventReceiver.SequenceNumber = sequenceNumber
     eventReceiver.Assembly = assemblyFullName
     eventReceiver.Class = assemblyClassName
     eventReceiver.Data = receiverData

   End Using
End Using

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