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.

Comments (13)

  1. williamcornwill says:

    smp Says:

    April 13, 2007 at 3:09 am

    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. williamcornwill says:

    Code Jedi Says:

    April 13, 2007 at 9:21 am

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

  3. williamcornwill says:

    crucial Says:

    June 5, 2007 at 4:14 am

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

  4. williamcornwill says:

    Code Jedi Says:

    June 5, 2007 at 9:32 am

    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. williamcornwill says:

    jeff Says:

    June 27, 2007 at 12:23 am

    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. williamcornwill says:

    jeff Says:

    June 27, 2007 at 12:37 am

    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. williamcornwill says:

    jeff Says:

    June 28, 2007 at 4:30 am

    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. williamcornwill says:

    Sriram Says:

    July 4, 2007 at 6:20 am

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

    Any workarounds or why it wouldnt work???

  9. williamcornwill says:

    tad Says:

    August 15, 2007 at 2:24 pm

    Where to put the console application?

  10. williamcornwill says:

    mosza Says:

    August 16, 2007 at 4:45 pm

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

  11. williamcornwill says:

    mosza Says:

    August 16, 2007 at 4:47 pm


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

  12. williamcornwill says:

    Harry Says:

    September 27, 2007 at 5:46 pm

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

    Thanks in advance.

  13. mkamoski says:

    All — Please help. How can I completely uninstall, delete, remove my orphaned EventHandler? Similar to Jeff’s note above, I have removed all traces of the assemby from the GAC using GacUtil.exe, I have removed all traces from the 12-hive "C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12TEMPLATEFEATURES" folder, I have run an iisreset, rebooted the server, etc, etc, and still I get the error in > Event Viewer, >Application, as: Event Category: General… Event ID: 6644… Event manager error: Could not load file or assembly ‘Cti.Pmp.DocumentLibraryEventHandler, Version=, Culture=neutral, PublicKeyToken=ee325f760b9d530e’ or one of its dependencies. The system cannot find the file specified. One of the problems that I have is that this assembly was installed with the wrong version and the wrong PublicKeyToken, so I suspect that is part of the issue. But, I need to fix it. How can this be fixed? Is it possible to uninstall by version? Thank you. — Mark Kamoski

Skip to main content