Walkthrough 1 – Developing a Simple Event Receiver

The planets in our solar system have a unique name. This walkthrough demonstrates how you can check if the name of the planet entered by the user doesn’t already exist in the Planets list. If it doesn’t exist, the creation of the planet can be done. If the name is already entered, the creation must be cancelled.

Preparation

1.  Create a custom list with the name Planet.
2.  Change the name of the Title column into Planet. Change the number of maximum characters to 100.
3. Add a column with the name Distance. This column will contain the distance to the sun and is of type Number.
4. Add a column with the name Moons. This column will contain the number of moons and is a column of type Number. Set the number of decimal places to zero.
5. Enter a first item with the following data:

a. Planet: Mars

b. Moons: 2

c. Distance: 229.000.000 (remark: this is the distance in kilometers)

Step 1 – Create the event handler

1. Open Visual Studio 2008 and create a class library project with the name UniverseEventHandlers.

2. Add a reference to the Microsoft.SharePoint.dll which can be found on the .NET tab under the label Windows SharePoint Services.

 

3. Add the following using statement to the top of the class file:

using Microsoft.SharePoint;

4. Give your class the name PlanetItemEventReceiver and let it inherit from SPItemEventReceiver.

public class PlanetItemEventReceiver: SPItemEventReceiver 

{

   // add your code here

}

5. Because you want to check the name of the planet before the data is saved, you have to implement the ItemAdding event. Add therefore the following code:

public override void  ItemAdding(SPItemEventProperties properties)

{

    base.ItemAdding(properties);

}

6. The properties argument contains information about the context. It contains properties like:

a. ErrorMessage

b. Status

c. ListId

d. ListTitle

e. ListItem

f. ListItemId

g. BeforeProperties

h. AfterProperties

i. CurrentUserId

j. SiteId

k. WebUrl

7. The method must contain the code to check the existence of the planet. The best way to do this is by using the SPQuery object, which can execute CAML queries against a SharePoint list. When a planet with the same name is found, the ErrorMessage and Status properties need to be set and the action must be canceled:

public override void  ItemAdding(SPItemEventProperties properties)

{

    // get the name of the planet that needs to be saved

    string planet = properties.AfterProperties["Title"].ToString();

    using (SPWeb web = properties.OpenWeb())

    {

       // get the Planet list (will be queried for existing planet name)

       SPList list = web.Lists[properties.ListId];

       // build the query

       SPQuery query = new SPQuery();

       query.Query = string.Format("<Where><Eq><FieldRef Name=\"Title\" /><Value Type=\"Text\">{0}</Value></Eq></Where>", planet);

       // execute the query

       SPListItemCollection items = list.GetItems(query);

       if (items != null && items.Count > 0)

       {

           properties.ErrorMessage = string.Format(

             "The planet with the name {0} already exists.", planet);

           properties.Status = SPEventReceiverStatus.CancelWithError;

           properties.Cancel = true;

       }

    }

}

Notice the using construction in the code:

using (SPWeb web = properties.OpenWeb())

{

}

This is necessary to dispose correctly from the SPWeb instance to avoid memory leaks.

8. That’s it for the code. Build the project.

Step 2 – Create the feature

The assembly containing the event handlers must be deployed to the Global Assembly Cache.

The best way to deploy an event handler is by creating a feature that can be installed and activated to be used and can be deactivated and uninstalled if not needed anymore.

1. As you are going to deploy the dll into the Global Assembly Cache (GAC), you have to sign the assembly. In the Solution Explorer right-click the project and choose Properties. Activate the Signing tab and choose a key to sign the assembly.

2. Build the project.

3. Create the following folder structure in the Solution Explorer:

4. The feature.xml file is an XML file containing the definition of the feature. Important here to now is:

a. The feature id: must be a unique Guid.

b. The scope: this can be

i. Web: accessible thru the current site.

ii. Site: accessible thru the current site collection and its subsequent sites

iii. WebApplication: accessible thru the current IIS web applications, the site collections and the subsequent sites in it.

iv. Farm: accessible thru the farm.

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

<Feature Id="{BDFA8DAD-F665-46a6-A4E4-87D012C0CEB2}"

    Title="Event Handlers - Walkthrough 1"

    Description="This feature demonstrates a simple event handler that checks the existence of a unique planet name."

    Scope="Web"

    Hidden="FALSE"

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

  <ElementManifests>

    <ElementManifest Location="elements.xml" />

  </ElementManifests>

</Feature>

 

5. The elements.xml file contains the definition of the event handler. Important here to note is:

a. Receivers: element that contains one or more Receiver elements. The Receivers element must contains a ListTemplateId attribute (indicating a list template type) or a ListTemplateOwner attribute (indicating the id of the list when installed through a feature).

b. Receiver: Each type of event handler is contained within a Receiver element.

c. Type: type of the event handler.

d. Assembly: the strong name of the assembly.

e. Class: the namespace and class name of the event handler.

<Elements Id="{F5610B81-A2E2-4957-ABF2-B8ECCD765AF3}" 

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

  <Receivers ListTemplateId="100">

    <Receiver>

      <Name>ItemAdding</Name>

      <Type>ItemAdding</Type>

      <SequenceNumber>1</SequenceNumber>

      <Assembly>UniverseEventHandlers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=841f382b41c47c60</Assembly>

      <Class>UniverseEventHandlers.PlanetItemEventReceiver</Class>

    </Receiver>

  </Receivers>

</Elements>

6. Add a last file to the root of the project and give it the name install.bat. This file will contain the necessary statements to install and activate the feature:

@SET TEMPLATEDIR="c:\program files\common files\microsoft shared\web server extensions\12\Template"

@SET STSADM="c:\program files\common files\microsoft shared\web server extensions\12\bin\stsadm"

@SET GACUTIL="c:\Program Files\Microsoft SDKs\Windows\v6.0A\bin\gacutil.exe"

Echo Installing the assembly in the GAC

%GACUTIL% -if bin\debug\UniverseEventHandlers.dll

Echo Copying files to TEMPLATE directory

xcopy /e /y TEMPLATE\* %TEMPLATEDIR%

Echo Installing Feature

%STSADM% -o installfeature -filename  “Planet Event Handler\feature.xml” -force

Echo Activating Feature

%STSADM% -o activatefeature -filename  “Planet Event Handler\feature.xml” –url “http://litwareinc.com” -force

IISRESET

Pay attention to the content of this file. The location of the GACUTIL utility depends on the Operating System you are running.

7. Save the project.

8. Open Windows Explorer and navigate to the location where you saved the project.

9. Double-click the install.bat file.

10. Open Internet explorer and navigate to the SharePoint site.

11. Try to add Mars again and note the error message on the beautiful error page.