SharePoint 2007 Deployment: Event Registration Features

Summary

This post is about developing features to register event receivers. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.

Package Structure

As I mentioned previously in the post SharePoint 2007 Deployment: Creating and Using Features, to build a feature you need to create the following files:

• The feature manifest file (which must be named feature.xml)
• One or more element manifest files

The feature manifest file contains the generic information about the feature package, and the element manifest files contain the information about each specific type of element that makes up the feature. Since I already explained all the possible contents of the feature manifest file in the above mentioned post, I will focus this one the element manifest that allows the registration of event receivers.

Additionally, you must include the assembly that contains the event receiver class in the solution package, so that it gets deployed to the Global Assembly Cache. Follow the instructions in the post SharePoint 2007 Deployment: Creating Solutions on how to package these three files (both manifests plus the assembly file) on a SharePoint Solution file.

Events Receivers

SharePoint allows you to handle several events that are fired according to actions performed on items, lists and web sites. Event are handled through event receivers, which are classes that implement a method for each event that is handled.

Once an event receiver is developed, compiled into an assembly and deployed to the GAC, it must be registered to a content type, a list or a web site in order to handle its events. That can be done through the API (or third-party tool such as Event Handler Explorer) or, concerning item and list event receivers, through this type of feature.

Allowed Scopes

The scopes to which a feature can be deployed, are dictated by the types of elements included in it. A feature with event registration elements can only be deployed to Web Site scopes.

Feature Manifest

I will only present a simple feature manifest, since the additional options were presented in the above mentioned post.

<?xml version="1.0" encoding="utf-8" ?>
<Feature
    xmlns="http://schemas.microsoft.com/sharepoint/"
    Id="{282902FB-0369-4f98-93C5-7FD7121CE164}"
    Title="My Event Receiver"
    Description="This feature registers My Event Receiver."
    Scope="Web"
    Creator="Create IT"
    Version="1.0.0.0">
  <ElementManifests>
    <ElementManifest Location="EventReceivers.xml"/>
  </ElementManifests>
</Feature>

Notes about this feature manifest:

• The title of the feature is My Event Receiver.
• It will be deployed as a Web Site feature, since it's Scope value is Web.
• It references a single element manifest file: EventReceivers.xml.

Element Manifest

The element manifest file can have any name you wish (in this example it's called EventReceivers.xml), but it's root element must be <Elements>. Inside this root element, you can place any number of feature element descriptions. In this example I will present the use of the <Receivers> element which is used to register event receivers that will handle list events.

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers 
    ListTemplateId="3500" 
    ListTemplateOwner="{11663D54-6152-4532-ABF5-FC08FAC216A7}">
    <Receiver>
      <Assembly>
        MyEventReceiver, 
        Version=1.0.0.0, 
        Culture=Neutral, 
        PublicKeyToken=6c0c7604915f786e
      </Assembly>
      <Class>MyEventReceiver.MyEventReceiver</Class>
      <Name>My Event Receiver</Name>
      <Type>ItemAdded</Type>
      <SequenceNumber>10000</SequenceNumber>
    </Receiver>
  </Receivers>
</Elements>

The example above registers an event receiver to all lists based on list template with ID 3500 that was deployed by a feature with the ID {11663D54-6152-4532-ABF5-FC08FAC216A7}. The receiver is the MyEventReceiver.MyEventReceiver class included in the assembly MyEventReceiver.dll that is installed in the GAC, and it handles the ItemAdded event on these lists.

The Receivers Element

The <Receivers> element is used to specify the list template to which the event receiver will be registered. There can be any number of <Receivers> elements in a single element manifest file. Here is a summary of the possible attributes of this element:

• ListTemplateId – (required) Specifies the ID of the list template to which the event receiver will be registered. If you wish to register an event receiver to one of SharePoint’s list templates, you can use one of the following values:
  • 100 – Generic List
  • 101 – Document Library
  • 102 – Survey
  • 103 – Links List
  • 104 – Announcements List
  • 105 – Contacts List
  • 106 – Events List
  • 107 – Tasks List
  • 108 – Discussion Board
  • 109 – Picture Library
  • 110 – Data Sources
  • 111 – Site Template Gallery
  • 112 – User Information List
  • 113 – Web Part Gallery
  • 114 – List Template Gallery
  • 115 – XML Form Library
  • 116 – Master Pages Gallery
  • 117 – No-Code Workflows
  • 118 – Custom Workflow Process
  • 119 – Wiki Page Library
  • 120 – Custom grid for a list
  • 130 – Data Connection Library
  • 140 – Workflow History
  • 150 – Gantt Tasks List
  • 200 – Meeting Workspace Series List
  • 201 – Meeting Workspace Agenda List
  • 202 – Meeting Workspace Attendees List
  • 204 – Meeting Workspace Decisions List
  • 207 – Meeting Workspace Objectives List
  • 210 – Meeting Workspace text box
  • 211 – Meeting Workspace Things To Bring List
  • 212 – Meeting Workspace Pages List
  • 301 – Blog Posts List
  • 302 – Blog Comments List
  • 303 – Blog Categories List
  • 1100 – Issue Tracking
  • 1200 – Administrator Tasks List
• ListTemplateOwner – (optional) Specifies the GUID of the Feature where the list template is defined, or the name of the site definition that registered the list.

The Receiver Element

The <Receiver> element specifies which class implements the event receiver and which list event it handles. There can any number <Receiver> child elements inside a <Receivers> parent element. This element has no attributes, but has six child elements, which are listed below:

• Assembly – The strong name of the assembly that contains the event receiver class. The strong name is composed of the name of the assembly (without the .dll extension), followed by a comma and the assembly version, followed by a comma and the assembly culture, followed by a comma and the assembly’s public key token.
• Class – The name of the class (including the namespace) that contains the implementation of the event receiver.
• Name – The name of the event receiver. This value is used to identify it if you wish to retrieve it through the API.
• Type – The event that the event receiver handles. Possible values are:
  • ContextEvent – The list received a context event.
  • EmailReceived – The list received an e-mail message.
  • FieldAdded – A field was added to the list.
  • FieldAdding – A field is being added to the list.
  • FieldDeleted – A field was removed from the list.
  • FieldDeleting – A field is being removed from the list.
  • FieldUpdated – A field was updated in the list.
  • FieldUpdating – A field is being updated in the list.
  • ItemAdding – An item is being added to the list.
  • ItemAdded – An item was added to the list.
  • ItemAttachmentAdded – An attachment was added to an item.
  • ItemAttachmentAdding – An attachment is being added to an item.
  • ItemAttachmentDeleted – An attachment was removed from an item.
  • ItemAttachmentDeleting – An attachment is being removed from an item.
  • ItemCheckedIn – An item was checked-in in the list.
  • ItemCheckingIn – An item is being checked-in in the list.
  • ItemCheckedOut – An item was checked-out in the list.
  • ItemCheckingOut – An item is being checked-out in the list.
  • ItemDeleted – An item was removed from the list.
  • ItemDeleting – An item is being removed from the list.
  • ItemFileConverted – A file was converted.
  • ItemFileMoved – A file was moved.
  • ItemFileMoving – A file is being moved.
  • ItemUncheckedOut – An item was unchecked-out in the list.
  • ItemUncheckingOut – An item is being unchecked-out in the list.
  • ItemUpdated – An item was updated in the list.
  • ItemUpdating – An item is being updated in the list.
• SequenceNumber – Specifies the order of the event receiver when more than one handler is associated with the same event. A high sequence number (10000 or higher) should be used to prevent problems with SharePoint’s own event handlers.
• Data – Specifies a string that will be passed as a parameter to the receiver method when handling the event.

Sample

You can download this sample here. This sample includes:

• The solution manifest file (manifest.xml).
• The solution cab structure file (solution.ddf).
• The feature manifest file (feature.xml).
• The event receiver element manifest file (EventReceivers.xml).
• A fake assembly (MyEventReceiver.dll) that must be replaced by your own assembly. Important: this file is not a real assembly containing an event receiver class, hence it will not work if deployed as is to your Sharepoint environment.
• A batch file (build.bat) that creates the solution package (MyEventReceiver.wsp).

Notice: This sample is given for illustrative purposes only and it should not be used as is in your SharePoint environment. Feel free to modify and use it as a template for your solutions and features.