Event Handlers in WSS v3

Those that are familiar with event handlers on Document Library lists in WSS v2 will be excited to know that event handlers can now be attached to any type of list. Not only do we get access to the Asynchronous events such as ItemAdded, we now also get access to Synchronous event before the fact, like ItemAdding. This will allow greater control over the way in which lists can be used within WSS v3.

This article will set out to describe the step by step instructions for defining an event handler and then hooking it up to a WSS list.

Creating the event handler

Creating an event handler is extremely simple, use Visual Studio .NET 2005.
1. Add a reference to the Microsoft.SharePoint assembly.

2. Create a class that inherits from one of the new event receiver classes, like SPItemEventReceiver or SPListEventReceiver.

3. Implement an override method for the event you wish to implement. Something like the following;

using Microsoft.SharePoint;

public class ListEventHandler : SPItemEventReceiver
public override void ItemAdded(SPItemEventProperties properties)
SPListItem listItem = properties.ListItem;
listItem[“ColumnName”] = “Hello”;
public override void ItemDeleting(SPItemEventProperties properties)
properties.Cancel = true;
properties.ErrorMessage = “Deleting items from the list is not permitted.”;

The ItemAdded event will set a column in the list called “ColumnName” to a value of ‘Hello’ and the ItemDeleting event will be cancelled with an error message displayed to the user.

4. The next step is to sign the assembly and deploy it to the GAC.

That is it; we have created our event handler and deployed it ready to a list to start consuming it. The next step is to register the event to be fired from a given list.

Registering the event handler with the list

In the previous version of WSS you could register the event handler using the SharePoint user interface. This facility has been removed in WSS v3. Registering the event handler in WSS v3 can be done in two ways, as a feature or via code. I will describe the registering via code method. For more information on creating a feature the article called “Working with Features” in the WSS SDK documentation.

The easiest way to register the event handlers against the list is to create a Console application, like the one below;

public class Program
static void Main(string[] args)
SPSite collection = new SPSite(“http://server/site/”);
SPWeb site = collection.OpenWeb();
SPList list = site.Lists[“MyList”];

string asmName = “MyEventHandlers, Version=, Culture=neutral, PublicKeyToken=f90218d0785d9063”;
string className = “MyEventHandlers.ListEventHandler”;

// Register the events with the list
list.EventReceivers.Add(SPEventReceiverType.ItemAdded, asmName, className);
list.EventReceivers.Add(SPEventReceiverType.ItemDeleting, asmName, className);

// Clean up the code

// Return to calling environment : Success

Basically, the code attaches to the SharePoint site and locates the list “MyList” then adds an item to the EventRecievers collection of the list for each event to be fired.

As you can see it is pretty easy to deal with the new event handlers in WSS v3. Happy coding.


20 Responses to Event Handlers in WSS v3

  1. smp says:

    Maybe someone could help me out. I have created an event handler and I can compile it, register it, line-by-line debug it, and (mostly) all is well. There is this one path in my code, however, that if a certain condition is met, then I want to set the properties.ErrorMessage to a text message and properties.Cancel = true. I have watched the debugger walk through these lines successfully, and it even throws the error screen, but it doesn’t display my message… it just says that there was a problem adding the new record and it couldn’t. If I share the code with someone, could they have a look? I can get the cheesy ItemDeleting examples (all over the web) to work, without a glitch. I am trying to do this in the ItemUpdating code and while it keeps stuff from being added, the error message (or lack) will surely stump my users.


  2. Code Jedi says:

    Can you please forward me the code and I will have a look for you! (Email me at william.cornwill@hotmail.com)

  3. crucial says:

    Would you do the same thing now to implement an event handler on a document library in WSS3?

  4. Code Jedi says:

    Document libraries in WSSv3 are also ultimately based on the list architecture. The process described in this article is applicable to any list (of any type) in WSSv3 – So Yes.

  5. jeff says:

    How can i remove an event handler added this way? I’ve created several versions of an event handler and it seems that an older version is running, instead of the current one.

  6. jeff says:

    Actually, I looked in the Windows/assembly folder and found the other versions still there. using gacutil.exe to install the handler to the GAC seems to have left the other ‘versions’ . When i tried to uninstall using the /u option, it told me that there were none matching the one that i just installed.

  7. jeff says:

    hello again, it seems that sharepoint is still wanting to load the other versions as I get an error in the event log that Sharepoint cannot find older versions of the library.
    Can you help me?

  8. Sriram says:

    ItemAdded() and ItemAdding() do not fire/work for lists at sitecolleciton level (“User Information List”)..

    Any workarounds or why it wouldnt work???

  9. tad says:

    Where to put the console application?

  10. mosza says:

    Hello Tad, you need to put your console app on the server running SharePoint as all related dlls will be available there.

  11. mosza says:

    it is common, that altering an assembly requires an iisreset for SharePoint to handle due to caching and all.

  12. Harry says:

    Can anybody give a snap of code for ItemAdding Event for a list/document library???

    Thanks in advance.

  13. Raj says:

    Excellent blog!

    How do you remove the event that is added (via console application) for the list?


  14. Ioana says:

    Thought I was crazy or smth: I wrote several EventHandlers for lists and they work just fine; and then I wrote one for the User Information List of a site collection, overriding ItemAdding, ItemAdded which don’t seem to fire.
    Then I saw Sriram’s post which states the same pb. Any hints?

  15. Mani says:


    I have an ItemAdded event handler which gets fires during an user creating a new topic and sends out the email to the distribution group. The distribution group can be entered using an E-Mail column which I have added.

    This part works fine.

    When I try to Reply to the message, I am using an ItemUpdated event handler. The problem is I am getting the body of the original message and not the reply one. How can I get this?

    Help highly appreciated.


  16. Pernille says:

    Ioana or Sriram:
    Did you find a work-around?
    I have same problem with the ItemAdded event on the userinfo list :o(

  17. Chris says:

    Great article – found via Google – needed a quick console app to register an Event Handler. Maybe I should write up a GUI app – pick site, pick list, pick event handler. (Think I saw something like this – but was a bit clunky)

  18. Søren says:

    For those of you who need to remove/delete an eventhandler (added by a console app), this tool is very useful: http://www.wssdemo.com/Lists/Resources/DispForm.aspx?ID=731

  19. Saurabh Kumar Singh says:

    Hi All,

    I am just associating a custom Event handler feature with SharePoint “User Information” list, for creating a copy of newly added user in another sharepoint custom list with the help of “ItemAdded” event handler, which will maintain user profile but it doesn’t seems to fire ItemAdding event with “User Information” list.

    I have read this article: “http://msdn.microsoft.com/en-us/library/aa979520.aspx”.
    Can you please suggest me that how can i handle events for “User Information” list?

    Thank you,
    Saurabh Kumar Singh

  20. Reh says:


    I have Annoucnment list which recieving email. I want to fire ItemAdded Event as soon as the email is recieved.

    Issue is that email is received successfully, but ItemAdded Event is not getting fired.

    Any CLue?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: