SPEventReceiverDefinition Class

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

Inheritance Hierarchy

System.Object
  Microsoft.SharePoint.Administration.SPAutoSerializingObject
    Microsoft.SharePoint.SPEventReceiverDefinition

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

Syntax

'Declaration
<SubsetCallableTypeAttribute> _
Public NotInheritable Class SPEventReceiverDefinition _
    Inherits SPAutoSerializingObject
'Usage
Dim instance As SPEventReceiverDefinition
[SubsetCallableTypeAttribute]
public sealed class SPEventReceiverDefinition : SPAutoSerializingObject

Remarks

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.

Examples

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.

string listName = "Contacts";
string siteURL = "https://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";
string receiverData = "Data";

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

using(SPSite site = new SPSite(siteURL))
{ 
   using (SPWeb web = site.OpenWeb()) 
   {
      SPList list = new SPSite(siteURL).OpenWeb().Lists[listName]; 
      SPEventReceiverDefinitionCollection eventReceivers =
         list.EventReceivers;

      SPEventReceiverDefinition eventReceiver = 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 ;

      eventReceiver.Update();
   }
}
Dim listName As String = "Contacts"
Dim siteURL As String = "https://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

     eventReceiver.Update()
   End Using
End Using

Thread Safety

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

See Also

Reference

SPEventReceiverDefinition Members

Microsoft.SharePoint Namespace

SPEventType