New Events in SharePoint Foundation 2010
Applies to: SharePoint Foundation 2010
To support improved performance and greater flexibility, several new events have been added to the Microsoft SharePoint Foundation 2010 developer platform. For a catalog of all events in SharePoint Foundation that includes notations on which of these events are new in SharePoint Foundation 2010, see Catalog of SharePoint Foundation Events.
New Add and Delete Events on Lists
Two new Add events have been provided for SharePoint lists – that is, for SPList objects:
The Add events take properties that are made available by using SPListEventProperties and are raised when a new list is created.
The ListAdding event allows users to cancel the creation of the list. Note, however, that you are advised not to cancel list creation when you are provisioning a site template or site definition. Note also that ListAdding events occur when you are restoring a site by using APIs in the Microsoft.SharePoint.Deployment namespace.
When you are deploying a solution, you can now set options that allow for disregarding events that occur during the deployment. The ListAdding event also occurs when a list is being restored after it has been recycled. This behavior is consistent with the way that SharePoint lists typically work. SPListEventProperties has two additional properties, TemplateId and FeatureId, which are passed as parameters so the developer who is using a ListAdding event can determine what type of list is being created.
In addition to these Add events, two Delete events have also been added to SharePoint lists:
These Delete events allow you to cancel a list delete operation at any point in the operation. When you cancel a delete operation, an error message passes back through the interface and an exception is thrown. Note that Delete events also occur when a list is being recycled (even if the list itself is not technically deleted). This behavior is consistent with the way that SharePoint list items typically work.
Delete events will not occur on narrowly scoped objects when higher-level objects are deleted. For example, if a Delete event occurs at the level of the Web site, then more narrowly scoped events – for example, those on individual list events – are not raised. For this reason, it is important to keep event scoping in perspective when coding your delete events. Note, too, that if someone deletes a stand-alone list folder (for example, the Lists folder inside of a Web site), there are no trappable events and the List events do not occur.
New Add Events on SharePoint Sites
Other new events provide more control and flexibility when you are creating a SharePoint site (an SPWeb instance). Note, however, that creating a SharePoint site involves two discrete steps: First, you add a site to the site collection (create an SPSite instance). At this point, the site itself is little more than an empty folder with a set of properties. Then, in the second step, you provision the site (that is, you apply a Web template). Then items such as lists, files, and other content objects are instantiated and organized based upon the specified site definition.
Because most of the important activity occurs during the provisioning phase, these new site-related events are associated with the process of adding and provisioning the site:
The WebAdding event is raised before a new Web site is created, so if the create operation is cancelled, then no SharePoint site is created and the provisioning process is not started. You can use the WebAdding event to perform activities such as conditional validation, which can ensure that the URL is valid, for example, or that the user who is creating a site has appropriate credentials.
The WebProvisioned event occurs after the Web is fully provisioned and the provisioning process has completed. This event can be configured to operate in either synchronous or asynchronous modes. Use this event to finalize development operations – for example, to add Web Parts to the site.
New Synchronous After Events
Synchronous after events are designed to meet needs that are only partially met by asynchronous events – that is, the ability to act on a list item after it has been submitted to the content database but before the user actually sees the list item. When synchronous after events occur, the event is processed before the event handler relinquishes control.
Note
The default synchronization behavior is synchronous for before events and asynchronous for after events.
Also available is a new property on the SPEventReceiverDefinition base class called Synchronization. This property has get and set methods to retrieve and set the SPEventReceiverSynchronization enumeration value. This enumeration provides a value called Default to support backward compatibility.
See Also
Concepts
Event Model Improvements for SharePoint Foundation 2010