Binding an Event Handler by Using the SharePoint Object Model

Applies to: SharePoint Foundation 2010

You can bind a SharePoint Foundation event handler by using event receiver base classes in the SharePoint Foundation object model. Our goal in this code sample is to bind the ItemAdded event that we created in Creating a SharePoint Event Handler to an SPSite instance.

Note

Microsoft Visual Studio 2010 provides project types that do much of the following work automatically when creating SharePoint events. Nevertheless, the following code examples are provided to illustrate the mechanisms for creating and binding events.

Create Binding Code Project

Open Microsoft Visual Studio and create a basic console application project and name it BindItemEvents. Then create a single class named Program.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Microsoft.SharePoint;

namespace BindItemEvents
{
    class Program
    {
        static void Main(string[] args)

Next, you must create references to your site and Web objects. Notice that references to the site and Web objects are established with the using statement. The reason for this is that it automatically calls the Dispose() method on the objects after the code block has executed. Alternatively, you can create instances of the site and Web objects in the code block; however, if you do you must be sure to dispose of these object once you have finished with them.

        {
            using (SPSite site = new SPSite("https://localhost")) 
            {
                using (SPWeb web = site.OpenWeb())

Now we create a list on the Web to which we’ve created a reference – that is, the document library named "Shared Documents". – and then you bind the event receiver definition.

{
                    SPList list = web.Lists["Shared Documents"];

                    SPEventReceiverDefinition def = list.EventReceivers.Add();

Notice, however, that simply adding the event receiver, EventReceivers, is not enough. The binding action also requires providing property values in order to define the receiver:

    def.Assembly = "ERDefinition, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=704f58d28567dc00";
    def.Class = "ERDefinition.ItemEvents";
    def.Name = "ItemAdded Event";
    def.Type = SPEventReceiverType.ItemAdded;
    def.SequenceNumber = 1000;
    def.Synchronization = SPEventReceiverSynchronization.Synchronous;
    def.Update();

The code example above indicates the most commonly used property values. To see a full list of available properties (and to see documentation for all of the properties), see SPEventReceiverDefinition. However, most important of the properties, and one that is required in all cases, is the Type property – in this case, ItemAdded. You must also specify the assembly by using the Assembly property, and the class – in this case, ERDefinition.ItemEvents, which you should have already created (as described in Creating a SharePoint Event Handler).

Note that the assembly name is provided by using a strong name. (You can obtain the assembly strong name by locating the assembly in the global assembly cache (GAC) and exposing the properties of the assembly.) Note, too, that the assembly strong name is a case-sensitive name. Use the SequenceNumber property to specify the order in which events are raised, in cases where an action raises multiple events. The Synchronization property allows you to specify whether the event is synchronous or asynchronous. Finally, you must run the Update() method.

Code Listing

Following is the full code listing for the activity described above.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Microsoft.SharePoint;

namespace BindItemEvents
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite site = new SPSite("https://localhost")) 
            {
                using (SPWeb web = site.OpenWeb())
                {
                    SPList list = web.Lists["Shared Documents"];

                    SPEventReceiverDefinition def = list.EventReceivers.Add();

                    def.Assembly = "ERDefinition, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=704f58d28567dc00";
                    def.Class = "ERDefinition.ItemEvents";
                    def.Name = "ItemAdded Event";
                    def.Type = SPEventReceiverType.ItemAdded;
                    def.SequenceNumber = 1000;
                    def.Synchronization = SPEventReceiverSynchronization.Synchronous;
                    def.Update();
                }
            }
        }
    }
}

See Also

Tasks

How to: Create an Event Handler Feature

Concepts

Binding a SharePoint Foundation Event Handler

Binding Event Handlers by Using SharePoint Features.xml