Event Handlers - How I Do Them - Part 1 - Code

The first thing I would say about event handlers is that if you want to test them really effectively, get the code you want to execute and set it up in a Console Application. That way at least you can step through it and have a good goo before consigning it to an event handler, firing it up and shouting at the screen when Nothing Bloody Well Happens. You will at least have the advantage of knowing that if Nothing is Bloody Well Happening, it is not the fault of your beautiful code. It will be Something Else, as it so often is. Many a slip between cup and lip.

Here is what you need to make an event handler:
The code, compiled into a DLL, installed and snug in the GAC (that's the place where all the dlls go to heaven)
The Feature. This is a PITA to do the first time, but once you've done one, you've done 'em all.

Starting with the code. Open Visual Studio and select an ordinary bog standard C# class library project. Call it something meaningful, but please please not too long because you have to type it out later to install it in the GAC. (Yes, I know there is a post-build instruction script. Not much use when you're working on one machine and deploying on another!)

Now presumably at this stage you'll know what you want your event handler to actually do. I tend to name them accordingly: e.g. OnItemAddedCopyItem, or OnItemUpdatedUserField. Let's say we want to do something simple like populate a field with a particular value. And you want to do it when the list item is first added to the list.

First, go over to the far right where the project is sitting, right click on the References node and select Add References. Scroll right down to the very bottom and select Windows SharePoint Services. This affords you the run of the SharePoint API. Hurrah. Now go back to your class file and at the top, where all the declarations live, add:

using Microsoft.SharePoint;


and then when you get the line where it declares the class:


public class MyClass


change that to


public class MyClass : SPItemEventReceiver


so it knows where it's inheriting from. We are piggybacking on the SPItemEventReceiver class so we can do our own stuff with it. Once we've done that, then the Intellisense will start to kick in. The dropdown will autocomplete when we enter the following line within the class:


public override void ItemAdded(SPItemEventProperties properties)


(I am typing this from memory, btw, so apologies for any errors in transcription. The Intellisense will make up for my thick eejitry. It's so good it even adds in the base.ItemAdded(properties) line and the little curly brackets!)


The properties object is going to be very important as it's the carrier of all the information of what the user has just put into the list. It contains a siteID (which is useful) a ListItem property (which is even more useful) and other properties which are accessible via the ParentList property. For some reason I can only get the Web of the properties object via the ListItem property, but hell, I don't mind as long as I get it. So we do something of this or suchlike:


SPListItem item = properties.ListItem;
item["MyStatus"] = "Updated By Event Handler";
item.Update();


You need that last line to explicitly tell it to update the list, otherwise it won't. If you call Update and you have an ItemUpdated event on the same event handler, call the DisableEventFiring method on the this object:
this.DisableEventFiring()
or you will have event handlers firing all over the place and god knows what mayhem. There is also a property called


properties.Cancel


which when set to true is the equivalent of Harry Enfield yelling "OI! NO!" at the user when he or she tries to do something. If you do this, do try and have an error message telling them so or they will be utterly baffled!


Ok, once the dll has been compiled with a strong key, error handling sorted (mirthless laugh at this one) and you are happy, the next step is to deploy the dll in the GAC. Fire up the command prompt, change the directory to wherever your copy of gacutil.exe lives and type:


gacutil -i c:\myPath\EventHandlerThing.dll


(This is where I invariably learn I have forgotten the strong key and have to compile it all over again.)


Once the component is installed in the GAC, we will need to get in to c:\windows\assembly and right click our component to get the public key token to put into the feature. Or, as I like to call it silently, the Effing Feature. But that is to be continued in our next...