Introduction to Events in SharePoint Foundation
Applies to: SharePoint Foundation 2010
The Microsoft SharePoint Foundation events model relies on managed components called event receivers that respond to SharePoint Foundation objects when specific triggering events take place. You create an event receiver by inheriting from one of the SharePoint event receiver base classes. After you have created the event receiver, you implement event handlers by overriding methods on the event receiver class. The class is then compiled into an assembly and placed in the global assembly cache (GAC); then, you bind your event handlers to an event host.
An event receiver is a piece of managed code that responds to SharePoint Foundation events whenever specific triggering actions occur on SharePoint objects. Triggering actions include activities such as adding, moving, checking in, checking out, and so forth. Objects that expect to receive events are called event hosts, which include objects like site collections, sites, lists, workflows, or features.
Almost any SharePoint object can raise events that are trappable by one or more of the event receiver classes. When categorizing a SharePoint event, it is useful to first think of the object on which the event is raised (that is, the event host) – for example, on a site collection, list, or list item – and then about whether the event is synchronous or asynchronous. For a list of SharePoint Foundation objects that raise trappable events, see Catalog of SharePoint Foundation Events.
SharePoint Foundation Event Model
The SharePoint Foundation event model is built upon a common set of components and concepts, which are summarized in the remaining sections.
Before and After Events
There are two categories of events – Before events and After events. Before events are raised when a specified action occurs before SharePoint Foundation writes back to the content database, and are therefore also referred to as synchronous events. This provides an opportunity for SharePoint Foundation to perform tasks after a specified action has occurred, but before data is committed to a database. A good example of the use of synchronous Before events is performing data validation, since Before events fire prior to commitment of data. You can also use Before (or synchronous) events to cancel user actions – for example, if data validation fails.
Event handler code that is triggered by a Before event – that is, a Before event handler – executes in the same process as the code that is executing the user action that triggered it. For this reason, Before events are always synchronous. Note that you can identify Before events because their member names end with the "-ing" suffix – for example, ItemAdding, ListAdding, and so forth.
After events, on the other hand, trigger event handlers that execute after user actions are committed to the content database and they invoke code that runs after the content database has been modified. This provides an opportunity to develop code that executes logic that occurs after a user has completed a specific action.
Because After events execute in a different process from the triggering action, they can execute either synchronously or asynchronously. You can identify After events because their member names end with the "-ed" suffix – for example, ItemDeleted, WebProvisioned, and so forth.
Event Hosts
Event hosts are objects, such as site collections, Webs, lists and list items, that expect to receive events – or, in other words, objects whose event receivers "listen" for SharePoint Foundation events. These SharePoint Foundation 2010 event host object types include instances of common objects such as SPSite, SPWeb, SPList, and SPContentType. Each of the event host types has specific event receiver base types from which you can inherit, to create an event receiver collection.
For a full list of host types and their event receiver types, see Table of SharePoint Events, Event Receivers, and Event Hosts and Catalog of SharePoint Foundation Events.
Event Receivers and Handling Events
SharePoint Foundation event handlers are a compiled module of custom managed code whose invocation is triggered by a specified event that you have specified. Event handler code is compiled into a .dll file and deployed to the GAC.
Event handlers in SharePoint Foundation provide exceptional flexibility in handling SharePoint events at a very granular level.
For information about how to develop an event receiver by using Visual Studio, see Creating a SharePoint Event Handler.
Binding Event Handlers
After your event handler code is compiled and deployed to the GAC, you need to bind it to a receiver object. Also known by the term "register," binding is the process by which event handler code is associated with an object type.
There are two ways to bind event handlers. One method uses declarative XML within a SharePoint Feature, either by list type or by content type. For more information, see Binding Event Handlers by Using SharePoint Features.xml.
The other method is to implement your event handler binding by writing code that implements classes in the SharePoint object model. For more information, see Binding an Event Handler by Using the SharePoint Object Model.
See Also
Tasks
How to: Create an Event Handler Feature
Concepts
Binding a SharePoint Foundation Event Handler