Announcing the SharePoint Toolbox shared source project on CodePlex along with CopyTimer and SPAlertPipeline
As the adoption of SharePoint increases within Microsoft, more and more teams are bound to develop useful tools and add-ons, which in the past would have been kept strictly internal to Microsoft. With the success of the Community Kit for SharePoint along with many other Microsoft founded shared source projects on CodePlex, these teams are now much more receptive to sharing the fruits of their labor with the rest of the world. Hence, I'm very pleased to announce the SharePoint Toolbox project on CodePlex located at http://www.codeplex.com/SPToolbox. This project will include powerful and useful tools and add-ons for SharePoint that help developers and IT pros implement SharePoint based solutions more quickly and managed them more effectively. Contributions will come from the Microsoft SharePoint Product Group, Microsoft SharePoint Online Services Group, Microsoft SharePoint Rangers consultants, and SharePoint MVPs.
We are kicking off the SPToolbox project with two useful tools:
- The first is called CopyTimer, which is a utility that performs a series of timed download/upload tests from/to a SharePoint server and records various additional information about the client computer such as latency, network connection, IP address, etc. See Sean Kelly's announcement earlier today for more details.
- The second is called SPAlertPipeline, which was developed by Steve Peschka and is described in detail below.
<Lawrence />
Hi, everyone – this is Steve Peschka here again from the SharePoint Rangers team. The SharePoint Alert Pipeline (or SPAlertPipeline for short) is the combination of a software tool and development methodology, which allows developers to create custom code that runs every time an alert fires. This allows you to introduce custom alert modalities besides just the standard email that SharePoint sends out when an alert occurs. For example, you could write custom code that sends an alert as a text message, an instant messaging alert, a tool to archive all alerts that get fired, and/or something else. It’s called an Alert Pipeline because your code gets injected into the process of firing the standard SharePoint alert email. You get access to all of the information about the item and event that triggered the alert and can use that in your custom code. The Alert Pipeline uses a registration process so that you can add as many custom alert handlers as needed for your scenario.
For those of you familiar with SharePoint Portal Server (SPS) 2003, you may recall seeing a similar concept in which the SPS 2003 alerting system allowed you to write code and register it so that the code would execute whenever an alert was fired. In Microsoft Office SharePoint Server (MOSS) 2007, the alerts architecture has been changed in such a way that the concept of a pipeline no longer exists out of the box. The SPAlertPipeline was developed to bring back a similar solution for those that relied on that type of alerting functionality in SPS 2003.
It’s not really well known, but alerts in MOSS do support using a custom assembly to process an alert. This is documented somewhat in the WSS SDK in the section describing the IAlertNotifyHandler interface. In short, there is an XML file that is used as a template for alerts called AlertTemplates.xml in the 12\TEMPLATE\XML folder. That single file contains templates for several kinds of alerts such as an alert for a generic list, document library, when an item is assigned to a user, etc. Each one of those alert templates includes a <Properties> element, under which you can define the custom assembly that should be executed. You do that by adding three elements:
- NotificationHandlerAssembly – the strong name of the custom assembly.
- NotificationHandlerClassName – the class name that should be invoked when the alert fires. It must implement the IAlertNotifyHandler interface.
- NotificationHandlerProperties – in most cases this will be blank, but you can optionally add any other custom data that you want to be available to your custom alert assembly when it fires.
The SPAlertPipeline takes advantage of this capability to provide the pipeline functionality. To use it, you start by making a copy of the AlertTemplates.xml file, and for every alert template in the file, you add the NotificationHandlerAssembly, NotificationHandlerClassName and NotificationHandlerProperties elements so that they referred to your custom Alert Pipeline assembly.
When you install the Alert Pipeline solution, it copies the custom alert template xml file to the 12\TEMPLATE\XML directory, registers the Alert Pipeline assembly in the Global Assembly Cache (GAC), and copies the AlertPipeline feature to the 12\TEMPLATE\FEATURES directory. It also registers a custom assembly that was created to add additional stsadm commands for managing the Alert Pipeline, and copies the Xml config file for the custom stsadm commands to the 12\CONFIG directory.
The Alert Pipeline feature is scoped to the web application -- that is, when it's activated, it modifies the web.config to add a custom configuration section handler. That allows the registration of all custom alert pipeline assemblies in the web.config file for that web application. It also makes a call to register the custom alert template xml file as the alert template file to use for all alerts going forward. When the feature is deactivated it restores the original alert template file that was shipped with MOSS.
Once the solution has been deployed and the feature activated, you can add or remove registrations for the Alert Pipeline using the custom stsadm commands:
- addpipe – add a new pipeline registration to a web application
- removepipe – remove a pipeline registration from a web application
- enumpipes – enumerate all of the pipeline registrations for a web application
If you want to create an assembly to use in the Alert Pipeline, you simply create a custom assembly that also implements the IAlertNotifyHandler interface, and you just register it in the GAC. This also gives you the flexibility such that if you decide you only want to use your custom alert handler, you can change the custom alert template XML file to refer to your custom assembly rather than the Alert Pipeline assembly.
The Alert Pipeline assembly, SPAlertPipeline, implements the IAlertNotifyHandler interface. The interface includes one required method, which is OnNotification. This method includes one parameter of type SPAlertHandlerParams. This parameter type includes all of the information about the alert, including what the alert is associated with, what/who caused it to be fired, etc.
The first thing that the SPAlertPipeline class does is to provide the out of the box behavior and send an email using the appropriate alert email template in the alert template XML file. Fortunately, that information is provided in an attribute of the SPAlertHandlerParams parameter called “body”. Thus sending the email requires only a single line of code:
SPUtility.SendEmail(new SPSite(ahp.siteId).OpenWeb(ahp.webId), ahp.headers, ahp.body);
The next thing the SPAlertPipeline does is to use the custom configuration section handler to enumerate all of the Alert Pipeline registrations for the web application. The custom section handler has a method to return a collection of assembly instances – one instance of each custom Alert Handler that was registered. The Alert Pipeline simply enumerates through each instance and calls its OnNotification method. So, the default alert action occurs when the Alert Pipeline is first called, and then one after the other, each additional alert handler is called as well.
I hope that you’ll find the SPAlertPipeline to be useful in building some really cool alerting solutions for SharePoint. If you have any questions, ideas, or success stories, please leave a comment.
Steve Peschka, SharePoint Ranger
