Creating event receivers in SharePoint 2007 with WSP builder

In my last post I described how to create a list event receiver. However it assumed some pre-existing knowledge of to to build and wrap wsp solutions together. I realized that maybe I should have described the actual process of building the solution as well, because some newcomers may not be familiar with that part.The first thing you need is WSPBuilder. This is going to make our life a whole lot easier. Once that’s installed in your VS2008 IDE, we’re all ready to go!

Creating your solution

The first thing we need to do is to create a new Visual Studio solution. Click File -> New -> New Project and you should get the regular New Project dialog. If you have WSPBuilder installed, you should see the WSPBuilder option under the Visual C# project type (or VB, if you roll that way). If you don’t see WSPBuilder, make sure it’s installed correctly (or at all).

Put in a name and directory and hit OK. You now have a newly created VS2008 solution. It’s pretty basic to begin with, so we’re going to add some stuff to it. First we need to add a reference to the SharePoint dll. Right click References and choose “Add Reference”. Navigate to the “C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI” folder, and select the Microsoft.SharePoint.dll file.

Next we need to create a feature to put our event receiver in. Inside your 12 folder, create a folder called “TEMPLATE” with another folder called “Features” inside that. This features folder is where your event receiver feature is going to live. You can put multiple features in a solution, but for simplicity, we’re only going to have a single feature here.

In your features folder, create a new folder for your feature. I like to name it in the style of Client-I’m-working-for.Project-I’m-working-on.What-it-does, but you’re welcome to name it whatever you want. You need to make sure it’s unique though, so you should at least prefix it with something easily visible (like your company or client name).

Now create two blank .xml files in that folder. One named feature.xml and one named eventreceiver.xml. Finally, create a new folder at the root of your C# (or VB) project named FeatureCode. Inside of this, create a new blank .cs (or .vb) class file named SampleEventReceiver.cs.

After all of this, you should have a solution looking something like this:

Creating the event receiver code

Now that our solution is all setup, it’s time to write some code to do whatever it is we want to do to the list. We’re not going to do anything complicated here. First we need to do is to add a using statement referencing the Microsoft.SharePoint namespace. After that’s done, we need to inherit the EventReceiver class that we want to implement. There’s SPItemEventReceiver and SPListEventReceiver, which work on items in a list and the list themselves, respectively. There’s also a couple of other ones you can inherit from. For our purposes, we’ll use the SPListEventReceiver.

Now inside your class start typing “protected override” and the magic of IntelliSense will show all the available events we can override.

Let’s pick the “FieldAdded” method. That means that whenever a field is added to the list, our code will run. Let’s add some basic code to test our functionality once it’s been deployed.

Code block

using Microsoft.SharePoint;

namespace ListEventReceiverSample.FeatureCode
{
    public class SampleEventReceiver : SPListEventReceiver
    {
        public override void FieldAdded(SPListEventProperties properties)
        {
            properties.List.Description = "Field Updated!";
            properties.List.Update();

            base.FieldAdded(properties);
        }
    }
}

So whenever a field is added to our list, the description of the list should change to “Field Updated!”. Not very useful, but it’ll demonstrate our receiver just fine.

Wrapping up the feature

Ok so we have our solution, and we have our code. Now we have to wrap it up in a nice feature that we can deploy to our SharePoint server. I’ve covered parts of this before, but I’ll do it again here anyway.

First let’s crack open our feature.xml file. It’s a blank file because we created it from scratch. The documentation on MSDN to create this is really good, and I usually just copy and paste their example and customize it to my needs.

Feature.xml documentation: http://msdn.microsoft.com/en-us/library/ms475601(office.12).aspx

Feature XML tag documentation: http://msdn.microsoft.com/en-us/library/ms436075(office.12).aspx

We don’t need the ActivationDependencies or Properties tags, so you can just delete those. In the ElementsManifests we need one ElementManifest tag to point to our eventreceiver.xml file. Also make sure that you create a new unique GUID for the Id attribute, and fill out your Title, Description and Scope to match what you need the event receiver to do. You also need to specify the xml namespace using the xmlns attribute, if this isn’t in the example (it’s not a the time I wrote this).

Code block

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
 Id="{4F2F7A38-F708-41BB-A2FF-53FC57CB5BF5}"
 Title="Sample List Event Receiver"
 Description="This is a sample."
 Scope="Web">
  <ElementManifests>
    <ElementManifest Location="eventreceiver.xml"/>
  </ElementManifests>
</Feature>

Make sure you have a look at the Feature XML tag documentation to understand what you can do here, and what options are available to you. We’re going to keep it pretty basic in our sample, but you have a lot of options.

Next we need to flesh out our eventreceiver.xml file. The documentation on how to register an event handler is located at http://msdn.microsoft.com/en-us/library/ms475328(office.12).aspx and http://msdn.microsoft.com/en-us/library/ms460929(office.12).aspx.

To be honest, you should probably read those documents rather than this blog post.

Anyway, our “eventreceiver.xml” is the “elements.xml” they are referring to. The name doesn’t matter, as long as you keep it consistent. You can copy and paste the code from that page, or create it from scratch if you want. But we do need to customize it a bit.

First of all, in the <Receievers> tag is where we want to specify exactly which lists we want to attach the event to. We do this using the ListTemplateId attribute. Set it equal to the Id of the list template you want to attach to. You can find a list of template ids at http://msdn.microsoft.com/en-us/library/ms431081(office.12).aspx. You can also attach to your own custom made list definitions, like I’m doing in this post.

The <Name> tag is, rather obviously, the name of your feature. I like to name this the same as the class in my code file.

The <Type> tag is the type of event you’re registering. We created a FieldAdded event receiver, so that’s the type we need to register.

The <SequenceNumber> tag specifies the sequence of registration when there is more than one event receiver in a feature. You should make these 10000 or higher.

The <Assembly> tag contains the strong name of the assembly. Check out this post for instructions on how to use Reflector to do so.

The <Class> tag should contain the name of the class that implements the event receiver. This is your class name, with it’s full namespace.

We won’t use the <Data>tag, so leave that blank. The <Filter> tag was never implemented, so you can delete that one if you copied from the example that includes it.

Now you should have something looking like this:

Code block

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers ListTemplateId="104">
    <Receiver>
      <Name>SampleEventReceiver</Name>
      <Type>FieldAdded</Type>
      <SequenceNumber>10000</SequenceNumber>
      <Assembly>ListEventReceiverSample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b76b58963356367a</Assembly>
      <Class>ListEventReceiverSample.FeatureCode.SampleEventReceiver</Class>
      <Data></Data>
    </Receiver>
  </Receivers>
</Elements>

And that should be it. Now we just need to build and deploy the feature and we should be good to go. To build your feature, just right click on your list event receiver sample project and choose “WSPBuilder” followed by “Build”.

The WSP file should now show up in the directory of your project.

Testing the event receiver

Ok so we have a WSP file and we want to test it. You have a few options for deployments here. You can use the built in WSPBuilder deployment options, or you can deploy using stsadm. I usually prefer stsadm (actually I prefer to make my SharePoint admin do it, I can’t stand deploying in 2007). I’m not going to go into detail here, because my post is already longer than I planned but you can use your favorite search engine if you need help with this step.

Once you have deployed your feature you need to activate it. Depending on what scope you set the feature to, head to the site settings of the web (or site settings of the site collection, if you chose Site as your scope) where you want the event receiver to do it’s magic. Find the feature and activate it.

Now head to the Announcement list (or create one first, if you don’t have one in your site) and add a new field to the list.

Fill in a name for the column, hit OK and you should see the results of your hard work.

And that’s pretty much all there is to it. If you want to take a closer look at the Visual Studio 2008 solution feel free to download the ListEventReceieverSample source code.