Building List Definitions with Event Receiver in Windows SharePoint

Windows SharePoint Services 3.0 introduces extended support for working with list events. The new event-handling support provides developers an even richer platform for developing custom integration points and building new types of applications on top of Windows SharePoint Services.

The Visual Studio 2005 extensions for Windows SharePoint Services 3.0 provide new support for creating SharePoint applications. The process of creating SharePoint list definitions and implementing list event handlers is significantly simplified. This Office Visual How To illustrates how to build a Windows SharePoint Services 3.0 list definition with an event receiver by using Microsoft Visual Studio 2005 and Visual Studio 2005 extensions for Windows SharePoint Services 3.0.

To illustrate how to build SharePoint list definitions with an event receiver, this section walks through three key steps:

1. Creating a SharePoint list definition project in Visual Studio.
   
   
2. Adding custom event-handling code to the item event receiver class that is generated by Visual Studio.
   
   
3. Building and deploying the list definition and event receiver to a SharePoint site.
   
   

Create a List Definition Project in Visual Studio 2005

By using the Visual Studio 2005 extensions for Windows SharePoint Services 3.0, you can easily create a suitable project for your list definition.

To create a SharePoint list definition project in Visual Studio 2005

1. Start Visual Studio.
   
2. On the File menu, click New, and then click Project. The New Project dialog box appears.
   
3. In the Project Types pane, click Visual C#, and then select the SharePoint category.
   
4. In the Templates pane, select List Definition. Specify a Name and Location for the project, and click OK. Visual Studio displays the List Definition Settings dialog box.
   
5. Select a base list definition, select Create an instance of this list (which occurs when you deploy the definition), and select Add with event receiver. Click OK. Visual Studio generates the list definition project.
   

Add Code to the Item Event Receiver Class

When Visual Studio creates the list definition project, it generates two Microsoft Visual C# source files: ListEventReceiver.cs and ItemEventReceiver.cs. These files contain the implementations of classes that are derived from the SPListEventReceiver and SPItemEventReceiver classes, with overrides of the list and item event-handling methods. This Visual How To illustrates handling the ItemDeleting event, the synchronous Before event that occurs before an item is deleted from the list.

To add custom handling of the ItemDeleting event

1. In the Visual Studio Solution Explorer, open the folder that has the same name as the project, and then open the ItemEventReceiver.cs source file.
   
2. Scroll down and locate the ItemDeleting method.
   
3. Add the following code to the body of the ItemDeleting method:
   
   C#

   properties.ErrorMessage = "Deleting of items not currently allowed.";
   properties.Cancel = true;
   

Build and Deploy the List Definition and Event Receiver

Before you can build and deploy the list definition and event receiver to the SharePoint site, you must enable the ItemDeleting event in the element manifest properties of the item event receiver feature.

To enable the ItemDeleting event

1. In Visual Studio, click Project, and then click projectname Properties. The project Properties dialog box appears.
   
2. Click the SharePoint Solution tab.
   
3. Expand the top-level Solution node, and then expand the node for the ItemEventReceiver feature. Click the Element Manifest node to display key/value pairs for the item events. (See Figure 1.)
   
   
   Figure 1. Enabling ItemDeleting event handler
   
   
4. Edit the entry for the ItemDeleting Enabled key to set its value to True.
   
5. Close the dialog box.
   

At this point the list definition project is ready to be built and deployed.

To build and deploy the list definition project

• In Visual Studio, click Build, and then click Deploy Solution. Visual Studio builds the assembly for the list event receiver and generates the necessary configuration files for deployment of the solution. It then deploys the solution to the SharePoint site and activates the list definition and list item event receiver features.
  

You can now test the list item event receiver by browsing to an instance of the newly created list definition, adding an item to the list, and then attempting to delete the item. Because the ItemDeleting event is being handled and canceled in the event receiver, Windows SharePoint Services cancels the deletion of the item and displays the message from the event receiver.

Read It

Windows SharePoint Services 3.0 extends list event handling in many ways:

• The scope of events now covers not only document and form libraries but also lists.
  
  
• Events that are triggered by lists can execute managed code when items are added, changed, or deleted.
  
  
• Events at the list level, such as adding or removing fields, can now be handled.
  
  
• Events are fired both before and after an action has occurred, allowing custom validation and potential cancellation of the event.
  
  
• Event handler responses can now be easily communicated back to the user.
  
  

This article illustrated how to build SharePoint list definitions with an event receiver by using Visual Studio 2005 and Visual Studio 2005 extensions for Windows SharePoint Services 3.0. The key steps include:

1. Creating a SharePoint list definition project in Visual Studio.
   
   
2. Adding custom event-handling code to the item event receiver class that is generated by Visual Studio.
   
   
3. Building and deploying the list definition and event receiver to a SharePoint site.