Windows SharePoint Services 3.0 event handlers

Events in WSS 2.0 supported document libraries but not lists. Moreover, version 2 supported only asynchronous events that fired after a user action had been committed to the SQL Server database. There was no way for the developer to cancel a user’s action inside an event handler.

WSS 3.0 improves event handling by retaining support for the asynchronous events that existed in version 2 and adding support for synchronous events that let you cancel user actions. For example, you can stop a user from deleting a document once it has been approved or from creating an order with an order date in the future. And events are supported on list items as well as on documents in a document library.

You create an event handler by writing a custom class that inherits from one of the WSS receiver classes and overriding methods to handle events. For example, to handle update events for items in a list, you’d create a class that inherits from the SPItemEventReceiver class and override the ItemUpdating method as shown below

Imports System
Imports Microsoft.SharePoint

Public Class MyReceiver : Inherits SPItemEventReceiver
    Public Overrides Sub ItemUpdating( _
            ByVal properties As SPItemEventProperties)

        Using web As SPWeb = properties.OpenWeb()
            Dim ListId As Guid = properties.ListId
            Dim ListItemId As Integer = properties.ListItemId
            Dim Orders As SPListItem = _
                web.Lists(ListId).GetItemById(ListItemId)
            Dim OrderDate As DateTime = _
                Convert.ToDateTime(Orders("OrderDate"))
            If OrderDate.CompareTo(DateTime.Today) > 0 Then
                properties.ErrorMessage = _
                    "You cannot enter orders for future days."
                properties.Cancel = true
            End If
        End Using

    End Sub
End Class

You can bind the event handler to a particular list or document library by either writing code against the object model or defining an event receiver in a WSS feature. For example, you can bind this event receiver to a list using code similar to this:

Dim list As SPList = web.Lists("Orders")
list.EventReceivers.Add(SPEventReceiverType.ItemAdding, _
    "[Fully-qualified Assembly name]", "Litware.MyReceiver")

WSS receiver classes use a naming convention for overridable methods that differentiates between synchronous and asynchronous events. For example, ItemUpdating is a cancelable, synchronous event that fires before the change is made to the content database.

There is a complementary asynchronous event named ItemUpdated that occurs after a change has been written to the content database. Unlike synchronous events, asynchronous events do not support canceling user actions. Instead they provide the means to perform a required operation after a change has been made to a document or list item, such as assigning the value of a calculated column or sending an e-mail notification.

In addition to supporting events on list items and documents, WSS 3.0 supports other new event types such as list events that fire when someone changes a list definition. For example, you can cancel the user’s action whenever someone tries to remove or rename a column in one of your custom lists. There are also events that fire whenever someone deletes or moves a site or an entire site collection.