Creating an Event Handler Feature

Event handlers are programs that enhance and add functionality throughout SharePoint sites and lists, manage events, and can be deployed to new and existing sites by using Features. The SharePoint object model includes several event classes that developers can use to develop and target event handlers specifically to items, lists, and sites.

In terms of deploying event handlers, in SharePoint Portal Server 2003 you can register event handlers through the administrative user interface, but this is no longer possible in SharePoint Server 2007. In SharePoint Server 2007, event handlers are deployed either by code, such as creating a Project Class to register an event handler, or as part of a Feature. Deploying event handlers with Features greatly simplifies the deployment process. You can use the Feature Receivers element to define the event handler assembly and provision the event handler as part of the Feature deployment. Add to this the ability to also activate and deactivate the event handler by toggling the Feature activation and deactivation settings, scope the event handler by using the Feature scope attribute, or targeting the Feature to a specific site during command-line activation, and you have a truly flexible solution.

This section demonstrates the steps involved in creating an event handler, using Visual Studio 2005, and deploying that event handler as part of a Feature. You'll review the type of events available to gain a better understanding of the type of functionality you can achieve by creating and deploying event handlers throughout your SharePoint sites.

Synchronous and Asynchronous Events

In addition to asynchronous events, SharePoint Server 2007 introduces synchronous events-that is, events that activate before the action occurs. An example of a synchronous event is one that can trap an item before it is deleted and remove the ability for users to delete an item, such as a file in a list or document library. Another example of a synchronous event is stopping users from adding columns to a custom list or document library. Asynchronous events, events that were possible in SharePoint Portal Server 2003, activate after an action occurs, such as appending an item to a list column or sending an e-mail after a file has been uploaded or a list entry has been made.

The SharePoint object model exposes several event classes, which ultimately inherit from the Microsoft.SharePoint assembly and directly inherit from the Microsoft.SharePoint.SPEventReceiverBase class. There are three main event classes:

• SPItemEventReceiver

• SPListEventReceiver

• SPWebEventReceiver

Each class includes both synchronous and asynchronous methods to work with events at the Item, List, or Web level. For instance, the ItemDeleting method, a synchronous member of the SPItemEventReceiver class, can be called to stop users from deleting files from a specific list or document library.

Table 26-8 shows examples of both synchronous and asynchronous event methods specific to each of the event class types: Item, List and Web. To view the full listing of events, launch the Visual Studio 2005 Object Browser, expand the Microsoft.SharePoint Assembly node, expand the Microsoft.SharePoint Namespace node, and then browse to each of the classes to view their respective event methods. You can also refer to the Windows SharePoint Services Software Development Kit (SDK) for an overview of the event classes.

Table 26-8: Examples of Synchronous and Asynchronous Events
Open table as spreadsheet

Event class	Synchronous event	Asynchronous event
SPItemEventReceiver	ItemDeleting	ItemDeleted
SPListEventReceiver	FieldDeleting	FieldDeleted
SPWebEventReceiver	SiteDeleting	SiteDeleted

Building the Solution

In this example, you will use Visual Studio 2005 to create a Project Class Library and create an event handler to stop users from deleting columns from a list. Then you will deploy that event handler as part of a Feature. To build a Solution, complete the following steps:

On the CD 

The following example is included on the book's CD in the \Code\Chapter 26 folder in the Visual Studio SharePoint solution, and includes the  cancelupdate.cs file and the SiteColumnHander Feature folder containing the  Feature.xml and  Elements.xml files.

1. Using Visual Studio 2005, create a new Project Class Library.

2. Add the references to the project, and code the solution.

3. Sign the assembly, build the Solution, and deploy Project DLL to the global assembly cache (GAC).

4. Create  Feature.xml and  Elements.xml files, and include the following:

   1. In the  Elements.xml file, specify the list instance to which the event handler will apply.

   2. Add the Project Assembly to the  Elements.xml file, and reference the  Elements.xml file in the Features.xml file.

5. Deploy the Feature by copying the Feature files to the Features directory on the front-end server.

6. Test your event handler.

Creating a New Project Class Library

In this section, you'll create a new class file,  cancelupdate.cs, for your event handler. To create the new class file, complete the following steps:

1. Launch Visual Studio 2005. On the File menu, click New Project to open the New Project dialog box.

2. Under Visual C# Templates, click Class Library.

3. In the Name text box, type the name of your project and then add the Location path. (This location, by default, is where your project will be built and DLLs will be output.) Click OK.

4. Change the name of the default Class1.cs file to  cancelupdate.cs. This is the file where you will code your event handler. (In this example, the class file is named  cancelupdate.cs.) Next, proceed to the "Adding a Reference" section.

Adding a Reference

You'll now add a reference to the Microsoft.SharePoint assembly so that you can access the necessary classes, methods, and properties for the project. To add a reference, complete the following steps:

1. On the Project menu, choose Add Reference to open the Add Reference dialog box.

2. Scroll down to Windows SharePoint Services. There are three references with the same name. Click the instance that references the following path:

   • %SystemDrive%\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI\Microsoft.SharePoint.dll

3. Click OK.

4. Add the Microsoft.SharePoint namespace at the top of the class file, and populate the remainder of the code as shown in the following code sample:

    using System; using System.Collections.Generic; using System.Text; using Microsoft.SharePoint; namespace SharePoint {     public class cancelupdate : SPListEventReceiver     {         public override void FieldDeleting(SPListEventProperties properties)         {             properties.Cancel = true;             properties.ErrorMessage ="You cannot delete columns from the" +  properties.ListTitle +" list.";         }     } } 

5. Save the populated class file.

Signing the Project

Next, you'll sign the project assembly. This adds a strong name and allows you to add the project DLL into the GAC so that you can deploy the project to your SharePoint sites. It also generates a public key token that you'll embed into the Feature elements file when registering the assembly as part of the Feature deployment.

To sign the project, complete the following steps:

1. On the Project menu, choose ProjectName Properties to open the Properties dialog box.

2. Click the Signing option to open the Signing tab

3. Select the Sign The Assembly check box, and choose New from the Choose A Strong Name Key File list.

4. In the Create Strong Name Key dialog box, name the Key and optionally include a password to protect the key file. Click OK.

   Your project is now strongly named and ready to be deployed.

5. Close the Properties window to return to your project. The signed key file will be included under the Solution Explorer window, denoted by the extension .snk.

6. Right-click the project name, and click Build to build the project.

   Monitor the build status in the project Output window, and make sure the project built successfully.

7. Minimize Visual Studio, and browse to the location path you specified for the project.

8. Expand the Bin directory under the project folder, and then expand the Debug folder where the project DLL is located.

9. Launch a secondary instance of Windows Explorer, and browse to the following location:

   • %SystemDrive%\WINDOWS\assembly

10. From the instance of Windows Explorer containing the Debug\Project DLL, select the DLL and drag and drop the DLL into the Assembly directory opened in the secondary instance of Windows Explorer.

Creating the Feature.xml and Elements.xml Files

Next, you'll create the Feature to deploy the event handler to your SharePoint sites. The Feature defines the list to which the event handler will apply and registers the project DLL to that list instance.

To create the Feature, complete the following steps:

On the CD 

These samples are also included on the companion CD in the \Code\Chapter 26 folder.

1. In the same project where you created the event handler, right-click the project name under the Solution Explorer window, click Add, and then click New Folder.

2. In the Name box, type Features.

3. Add another folder under the Features folder, and name that folder SiteColumnHandler. Then add two new .xml files to the SiteColumnHandler folder by right-clicking the project name, clicking Add, clicking New Item, and selecting XML File. Name the files  Feature.xml and  Elements.xml, respectively.

4. Populate the  Feature.xml file with the following code (optionally generate your own GUID for the Id attribute):

    <?xml version="1.0" encoding="utf-8" ?> <Feature   Id=""   Title="Disable deletion on Document Library columns"   Description="The Feature includes an event handler which will stop users from deleting columns from document libraries on a site."   Scope="Web"   Hidden="FALSE"   ImageUrl=""   xmlns="http://schemas.microsoft.com/sharepoint/">   <ElementManifests>     <ElementManifest Location="elements.xml"/>   </ElementManifests> </Feature> 

5. Populate the  Elements.xml file with the following code.

   The  Elements.xml file defines on which list the event handler will work. In this case, the list is specified as type "101", which is the base type for the document library. But you can define another list type or create your own custom list and define that. The  Elements.xml file also includes the assembly and class references for the event handler.

    <?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/">   <Receivers ListTemplate>     <Receiver>       <Name>cancelupdate</Name>       <Type>FieldDeleting</Type>       <SequenceNumber>1000</SequenceNumber>       <Assembly>SharePoint, Version=1.0.0.0, Culture=neutral, PublicKeyToken =ad7f6a147689147c</Assembly>       <Class>SharePoint.cancelupdate</Class>       <Data></Data>     </Receiver>   </Receivers> </Elements> 

   Note 

   In the Assembly attribute, SharePoint is the name of the project. In the Class attribute, SharePoint is the name of the project, cancelupdate is the name of the class file including the event handler. The PublicKeyToken is the key that was generated when you signed the project assembly. You can get this key either by accessing the project DLL you added into the GAC and copying it, or you can use Lutz Roeder's Reflector for .NET tool, which will expose the project assembly information, including the public key token. Download the Reflector tool from http://www.aisto.com/roeder/dotnet/.

6. Save and close both files, and minimize Visual Studio.

Deploying and Testing a Feature

Now that you've created the project, deployed the DLL to the GAC, and created and configured the Feature, you can install and deploy the Feature.

To install and deploy the Feature, complete the following steps:

1. Open Windows Explorer, and browse to the Project Feature directory, which will be under the Project directory specified in the location path when you created the project.

2. Copy the SiteColumnHandler folder, and paste it into the Features directory.

3. To install the event handler Feature and make it available for activation on your SharePoint sites, open the Windows command-line tool, browse to the stsadm.exe location, and type the following command:

    stsadm.exe -o installfeature -name sitecolumnhandler 

4. Browse to the SharePoint site where you want to activate the Feature.

5. On the Site Actions menu, choose Site Settings to open the Site Settings page.

6. Click Site Features under the Site Administration column to open the Site Features page.

7. Locate the new Feature, named Disable Deletion On Document Library Columns, and click the Activate button in the Status column to activate the Feature.

8. Test the Feature by going to one of your document libraries, such as Shared Documents. Go into the Document Library Settings and attempt to delete one of the existing columns. If your Feature has been successfully installed, you will receive an error page with the message, "You cannot delete columns from the <name of document library> list."

   Note 

   If you update your event handler project class file, you need to rebuild the project, add the updated DLL to the GAC, and perform an IISRESET to make any changes to existing instances of the event handler throughout your SharePoint sites. Unless you've made changes to the Features files, such as  Feature.xml or  Elements.xml, you do not need to reinstall the Feature to make changes to an existing event handler instance.