Event Handlers - Part 3: Register Event Handlers plus free Site Settings – Manage Event Handlers Add-on solution
This post is the third post of a 3 post series.
Post 1: Everything you need to know about MOSS Event Handlers
Post 2: Developer Solution Starter Kit (Building and deploying event handlers to MOSS)
Post 3: Registering Event Handlers plus Site Settings - Manage Event Handlers
In the first post, I discussed the benefits of using Event Handlers in Microsoft Office SharePoint Portal Server 2007 (MOSS).
In the second post, I discussed how to develop and deploy Event Handler solutions for Microsoft Office SharePoint Portal Server 2007 (MOSS).
In this post I will discuss the various mechanisms to attach (register) your event handler assembly to a site, list, or content type. The "Site Settings – Manage Event Handlers Add-on" solution is hosted on CodePlex. Here is the link:
Codeplex Project : http://www.codeplex.com/SPSCustomAdmin/
(If any of you are interested in getting involved, I am interested in building more Site Settings addons. Please email me at brwil at microsoft dot com if you would like to get involved in expanding this framework. I will discuss the ideas i have in more detail in a future blog post.)
Overview
So you have deployed the assembly to the farm, now what? How do I register an event in your assembly for a Site, List, or Content Type?
I will describe three ways to deploy your assembly’s events.
1) Manage EventReceivers via Code
2) Deploy event handlers using the Feature framework of MOSS 2007
3) A cool custom Site Settings Application I built to manage (view, add, edit and delete) event handlers.
Managing EventReceivers via Code
The site (SPWeb) object, the list (SPList) object and the Content Type (SPContentType) object expose a collection called EventReceivers based on the SPEventReceiverDefinitionCollection class.
This collection maintains a set of SPEventReceiverDefinition objects (events) attached to a site, list or content type.
Adding Event Handlers (SPEventReceiverDefinition)
This class provides an “Add” method to attach a new SPEventReceiverDefinition (We created and deployed these to MOSS in Post 1 and 2.) The Add method asks for three bits of information:
· SPEventReceiverType: This tells SharePoint the type of event receiver we are adding to the EventReceiver collection.
· Assembly name: The name of the assembly. E.g. “Litwarehandlers, Version 1.0.0.0, Culture=neutral, PublicKeyToken=a6ab42c509981682”
· Class name: The name of the class. E.g. “Litwarehandlers.SiteHandlerClass”
(An easy way to get this information is to use our trusty old friend, Lutz Roeder’s Reflector application. Simply reflect the class and copy and paste the information you need.)
Once attached, the site, list or content type will now start picking up these events and executing your assemblies code.
Modifying Sequence Numbers
Another important property you may want to set for each event you attach is the Sequence Number. The sequence number determines the order your event assemblies’ fire. This is especially important when you have created multiple assemblies that are all attached to the same Site, List or Content Type event.
To modify the Sequence Number, you need to retrieve the SPEventReceiverDefinition object from the EventReceivers collection.
· Site: site.EventReceivers
· List: list.EventReceivers
· Content Type: site.ContentTypes[content type name].EventReceivers
A suggested best practice (and only my opinion), do not use sequence numbers below 10000 as SharePoint uses event handlers extensively to run SharePoint Workflows, etc. These event handlers use Sequence Numbers, starting at 1000.
Deleting Event Handlers (SPEventReceiverDefinitions)
When removing definitions, here is what you have to do:
Site:
· Attach to the site (SPWeb)
· Lookup the SPEventReceiverDefinition object in the site.EventReceivers collection.
· Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.
· Call the site.Update() method.
List:
· Attach to the site (SPWeb)
· Retrieve the list : (site.Lists[GUID or listname])
· Lookup the SPEventReceiverDefinition object in the list.EventReceivers collection.
· Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.
· Call the list.Update() method.
Content Types:
· Attach to the site (SPWeb)
· Retrieve the SPContentType (site.ContentTypes[SPContentTypeId])
· Retrieve the SPEventReceiverDefinition object : (SPContentType.EventReceivers[GUID])
· Use the delete method of the SPEventReceiverDefinition object to remove it from the collection.
· Call the SPContentType.Update() method.
Managing assemblies using Features
It is possible to create a feature that deploys your event handler to the assembly.
MSDN has an example on how to achieve this: http://msdn2.microsoft.com/en-us/library/ms453149.aspx
See screenshot of the xml you need to write to deploy an event via the features framework:
Limitations:
· It is difficult to see what event handlers are installed and the sequence they are firing for a site, list or content type. To modify, requires rebuilding the feature with the correct settings.
· Using a feature, “hardcodes” the event handler to an individual list or Content Type. Each time you want to use the SAME event handler, you are forced to write another feature to register it.
In my opinion, wrapping functionality as a feature is cool, but is overkill for registering event handlers. This is my reason for building a view, add, edit and remove application via Site Settings. See below! J
Managing EventReceivers using Site Settings application assemblies
Features
The Manage Event Handler site settings application provides you with the ability to view all events that have been associated to a site, any list of that site, and all Content Types for that site.
You can add event handlers, edit the sequence numbers and delete events registrations. Once the feature is activated, it is accessible from the Site Settings of any site
Feature – Event Handler Screenshot
Site Settings Event Handlers Screenshot
View Event Hhandlers Screenshot:
Add Event handlers Screenshot:
Edit Event handlers Screenshot:
Delete Event handlers Screenshot
Firstly, download the solution deployment code and wsp file from CodePlex here, and install in your SharePoint environment. (If you pick up any issues or have feature requests, please let me know so that I can add these to future releases.)
How to install
1. Follow the steps in my previous post in the "Deploying your assembly to staging and production" section. It provides step by step instructions on how to install a wsp file.
2. Navigate to any site and open Site Settings.
3. Open “Site Features” under the Site Administration column.
4. Activate the new feature called “Manage Event Handlers”. This enables event handler management application for this site.
5. Navigate back to Site Settings. A new option is now available under the “Site Administration column” called “Manage Event Handlers”. Select this option.
Notes
I have removed the ability to edit or delete native SharePoint generated event associations as this may affect the stability of SharePoint Out-Of-The-Box functionality. Only YOUR events can be managed.
Content Types (and their associated event handlers) can only be managed via the root site of the site collection.
In case you are wondering how to go about building your own site settings applications I have posted the code on CodePlex. I am planning on building an additional site settings administration application to manage and configure site properties.
Summary
If you have any questions, add a comment and time permitting, I will try to respond as soon as possible.
