Synchronous and Asynchronous Eventhandling

The idea of events and eventhandling is simple. When an event occurs (a typical example in SharePoint: an item is added to a list or library) the system looks for all registered listeners waiting for this event to happen. These listeners are implemented by pieces of code (methods) that confirm to the following standards:

  • The class the method is contained in is derived from SPItemEventReceiver
  • The method name is equal to one of the entries of the enumeration SPEventReceiverType
  • The return value of the method is void
  • The signature of the method contains one parameter only of type SPItemEventProperties
  • The method has public visibility and is non-static

In conclusion, the method you write overrides an existing method from the SPItemEventReceiver class. A sample would look like this:

namespace MyEventReceivers 
{
  public class MyFirstEventReceiver : SPItemEventReceiver 
  {
     public override void ItemAdded(SPItemEventProperties properties)
     {
       // your code that executes when event occurs here.
     }
  }
}

Now that an eventreceiver has been created this needs to be compiled in an assembly and transported to the GAC using either on a testmachine a tool like gacutil (search for gacutil.exe on your system, it should be provided with .NET SDK) or directly creating a solution with either wspbuilder, visual studio extensions for SharePoint 2007 or manually writing a manifest and using the makecab command.

To inform SharePoint that it should execute your code whenever a certain event (in our case the ItemAdded event, which is an asynchronous event) occurs you need to register the receiver on the object you want to use.
ItemAdded is typically a list event, so we will register the event receiver on a list with the name MyListWithEventReceiver. You can do this either using Microsofts xml notation and deploying the solution or you can use a feature or executable (only development system) to do this.

public static void Main(string[] args)
{
  const string listName = "MyListWithEventReceiver";

  const string assemblyName = "MyAssemblyFullName";
  const string eventReceiverName = "MyFirstEventReceiver";

  using(SPWeb web = new Site("http://myServer:myPort").OpenWeb())
  {
       SPList list = web.Lists[listName];
       list.EventReceivers.
             Add(SPEventReceiverType.ItemAdded, 
                   assemblyName, 
                   eventReceiverName);
       list.Update();
  }
}

Check out this link and Dave Hunter’s Blog as well.

Important to know now is that everytime you write code to insert an item and then use a SPList.Update() call from our generic list your code will be executed. If for some reason you don’t want this, you can turn it off by using the DisableEventFiring() method as I explained here.

Of course this will also occur whenever someone adds an item to your list using the web front-end of SharePoint.

Now that the basics of SharePoint Events and EventReceivers are laid out to get to the topic at hand:
The difference between synchronous and asynchronous eventhandling. Synchronous events such as “ItemAdding”, “ItemUpdating”, “ItemDeleting” are executed logically during the event itself, asynchronous events are handled after the event has taken place.

So the “sync events” can be typically used for validation testing, the “async events” for consecutive actions, very much like workflows. “Async events” can be seen as primitive one-step workflows. Of course workflows can do a lot more, including waiting on human interaction to determine the next execution step.

Programatically, how does this effect the objects at your disposal?
The properties object contains an SPWeb object, which you can use to get all your object or identify the working web and create a new one with elevated privileges. You also have the BeforeProperties, AfterProperties and ListItem members.

The “async events” have the ListItem member, because it has been created already, the “sync events” have the before and afterProperties, which contain the values from the form, that was used to change the listItem. So it is always error-prone to change existing eventreceivers from async to sync and vice-versa.

Happy SharePointing!

The SPEventReceiverType enumeration gives an idea of all the events you can create listeners for.

Advertisements

One Response to Synchronous and Asynchronous Eventhandling

  1. Pingback: The trouble with editing items on synchronous add-events « SharePoint 2007 Hut

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: