Event Handlers - How I Do Them - Part 2 - Features

If all has gone well, we have a compiled dll sitting in the GAC of the machine where Sharepoint lives. However SharePoint does not have a bull's notion that this dll exists so it cannot execute it on the required event. In order to hook up the two parties, we need to create a Feature.

In SharePoint proper, features live in the page known as Site Features in the Site Settings screen. Click on that and generally you will see a list of features. Click Activate and these get Activated. What we want to do is add in our feature so that SharePoint can see it too.

This requires an introduction to that fearsome region known as the Twelve Hive.

The Twelve Hive is a nickname for the forest of folders which contains all the SharePoint system stuff and web configs and the like. Tamper with these at your peril. The most irritating thing about this Twelve Hive is that all the files you need are neck deep in the midst of long folder paths. The system paths will vary but generally to find the features, one should navigate to

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\FEATURES

Create a new folder with your event handler name in the Features folder. It doesn't really matter if you call it Mickey Mouse, to be honest, but it helps for clarity when you call it from the command line later. Then you need to create two xml files: Feature.xml and Elements.xml. To save you tearing your hair out, here are two samples I made earlier:

Feature xml:

<?xml version="1.0" encoding="utf-8"?> <Feature Scope="Web" Title="Event Handler of uncertain provenance" Id="CD603E5F-0148-4ce0-B4EC-FB0ECB138A03" xmlns="http://schemas.microsoft.com/sharepoint/"> <ElementManifests> <ElementManifest Location="elements.xml"/> </ElementManifests> </Feature>

A brief explanation: Scope="Web" is what is most useful when working with events on document libraries, lists and other objects that exist in the SPWeb object scope. Scope = "Site" is only useful when programming site event handlers e.g. stuff that happens when you create a subsite. A bit like UHT milk, as Pat Mustard might have noted. Observant folk might ask: what's that long streel of a thing in the ID field and where did she get it from? Answer is that it's a GUID and you can get one by going into Visual Studio, selecting Tools menu and Create Guid. Simple as that. Oh and don't use the one in the sample - you need to get your own for each feature. That's how Sharepoint keeps track of them. It loves GUIDs.

Elements xml:

<?xml version="1.0" encoding="utf-8" ?>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

  <Receivers ListTemplateId="100">

    <Receiver>

      <Name>[YourDLLName]</Name>

      <Type>ItemAdded</Type>

      <SequenceNumber>20100</SequenceNumber>

      <Assembly>

        [YourDLLName], Version=1.0.0.0,

        culture=neutral, PublicKeyToken=[get it from the GAC]

      </Assembly>

      <Class>[YourDLLName].[YourEventReceiverClassName]</Class>

      <Data></Data>

      <Filter></Filter>

    </Receiver>

</Receivers>

</Elements>

This is a bit meatier. List Template ID refers to what kind of list it is. Generic list is 100, Document Library is 101, Issue List is something else. If in doubt, google "SharePoint List Template ID" and then decide which one fits. If you want to fire it off more than one type of list template, then you need to put in an event receiver for each one - that will be the <receivers></receivers> tags. Type is the event handler type, in this case ItemAdded. You will need a second one for ItemUpdated, and another one for ItemDeleted, should you have those also. Anything in square brackets is already defined when you compiled your assembly and you can get the public key token from the GAC. The sequence number just needs to be high enough to be unique.

So we have our feature files. Now it gets ugly and awkward. The only way we can install our feature (good readers feel free to correct me) is via an inelegant little tool called STSADM, which can be found, yes you guessed it, buried way way down in the Twelve Hive. You will generally find it somewhere similar to here:

C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN\


So open up a Command Prompt window, cd to the above location or similar, and type the following piece of Shakespeare:


stsadm.exe -o installfeature -filename [YourFolderName]\Feature.xml


replacing YourFolderName and removing the square brackets of course. If all goes well, you're admin and king of the castle and the xml is well-formed, you should get a confirmation that the feature installed successfully. Once that done, you generally can forget about the feature unless there's an error in it. Most errors in features come from muggins like me copying files from elsewhere into the new folder and forgetting to change the assembly names, but never mind that, let's move on...


Navigate to the sharepoint site where you wish to deploy your new spiffy event handler. This does not have to be the top site, it can be several levels down. Go to Site Settings - Site Features. Your event handler will show up. Click Activate. Then go to your list, add /edit/delete your item and see if your field is updated. If not, never fear, you can debug it or instrument it. I always find the debugger a slippy process (oh for SP 2010 and its integrated environment!) so I will come back with some error handling code you can try.


But hopefully it works for you!