Understanding the Event Receivers

Event receivers, as the name suggests, allow you to subscribe and respond to events that occur to SharePoint items such as sites, lists, list items, and so on. For example, you may want to send out a notification when a new site is provisioned or prevent deletion of a list item based on certain conditions. Event receivers help you to achieve just that, by enabling your code to subscribe to various events and then responding accordingly.

Hour 11, “Understanding Advanced Data Management Concepts in SharePoint 2010,” looks at event receivers for lists and list items. This section explores event receivers associated with sites in more detail.

Consider a scenario where you want to log information about every newly provisioned site and disallow users to delete a site. To deal with the scenarios, create a new Event Receiver project or create an Empty SharePoint Project and add then an event receiver project item.

Choose to handle the Web Events and select the A Site Is Being Deleted and A Site Was Provisioned events, as shown in Figure 7.19.

Figure 7.19. Creating an Event Receiver project

A Site Is Being Deleted event is called at the time of site deletion but before the actual site deletion, so that you have the option of programmatically cancelling the deletion request. A Site Was Provisioned is called after a new site has been created. In case you have a requirement to cancel the site creation based on some criteria, you should be handling the A Site Is Being Provisioned event instead.

Now look at the code you need to put into the A Site Was Provisioned event receiver:

public override void WebProvisioned(SPWebEventProperties properties)
{
    // Get reference to current web and the root web
    SPWeb currentWeb = properties.Web;
    SPWeb rootWeb =currentWeb.Site.RootWeb;

    // Get reference to the SiteProvisioningTrackerList
    SPList list = rootWeb.GetList("/Lists/SiteProvisioningTracker");

    // Create a new list item and update its titile
    SPListItem listItem = list.AddItem();
    listItem["Title"] = "Web Provisioned: " + properties.Web.Title;
    listItem.Update();

    // Activate our EventReceiverDemoFeature in the newly provisioned site
    currentWeb.Features.Add(new Guid("{c5c61302-6296-4c9c-ad77-130b5af56407}"));
    currentWeb.Update();
}

As demonstrated previously, we get a reference to the root web and add a new list item in the SiteProvisioningTracker list indicating the provisioning of a new site. Further, note that we are deploying the event receivers via site scoped feature. Hence we activate the feature in the newly provisioned site as well by calling the Features.Add method and passing the ID of our feature to the same as a parameter.

The preceding code results in the entries shown in Figure 7.20 being made in the SiteProvisioningTracker list:

Figure 7.20. Logging site provisioning information to a list

Next examine the code we need to write to disable site deletion and also display the appropriate error message to the user:

public override void WebDeleting(SPWebEventProperties properties)
{
    // Prevent site deletion and throw "Site deletion is not Allowed." error
    // message to the user trying to delete the site
    properties.Status = SPEventReceiverStatus.CancelWithError;
    properties.ErrorMessage = "Site deletion is not Allowed.";
    properties.Cancel = true;
}

Now whenever an end user tries to delete a site that has our feature activated, she receives the error message as shown in Figure 7.21.

Figure 7.21. Preventing site deletion

Thus you can see that event receivers make it convenient to plug in our custom code and respond to various events that occur to SharePoint items.