SharePoint 2007–Event Handlers

SharePoint isn’t just an application.  It is an extensible application platform.  Easily extended with features that allow you to add custom event handlers to sites, lists, items and content types in your portal. A custom event handler is a .Net assembly that contains the additional business logic you need to run when the event occurs in SharePoint.

Examples of custom event handlers can include things like:

• Retrieve information from a database such as filling in the remaining fields of a list based on a CustomerID (assuming you don’t have an enterprise license for BDC)
• Call a web service
• Start a workflow
• Perform list data validation
• Convert document to PDF and store in alternative library.

Event Types

Microsoft.SharePoint.SPWebEventReceiver : "Site Level"

 

SiteDeleted	Occurs after a site collection has been deleted.
SiteDeleting	Occurs when a site collection is being deleted.
WebDeleted	Asynchronous Afterevent that occurs after an existing Web site is completely deleted.
WebDeleting	Synchronous before event that occurs before an existing Web site is completely deleted.
WebMoved	Asynchronous after event that occurs after an existing Web site has been moved.
WebMoving	Synchronous before event that occurs before an existing Web site has been renamed or moved to a different parent object.

 

Microsoft.SharePoint.SPListEventReceiver : "List Level"

 

FieldAdded	Occurs after a field link is added.
FieldAdding	Occurs when a field link is being added to a content type.
FieldDeleted	Occurs after a field has been removed from the list.
FieldDeleting	Occurs when a field is in the process of being removed from the list.
FieldUpdated	Occurs after a field link has been updated
FieldUpdating	Occurs when a field link is being updated

 

Microsoft.SharePoint.SPItemEventReceiver : "List Item Level"

ItemAdded	Asynchronous After event that occurs after a new item has been added to its containing object.
ItemAdding	Synchronous before event that occurs when a new item is added to its containing object.
ItemAttachmentAdded	Asynchronous after event that occurs after a user adds an attachment to an item.
ItemAttachmentAdding	Synchronous before event that occurs when a user adds an attachment to an item.
ItemAttachmentDeleted	Asynchronous after event that occurs when after a user removes an attachment from an item.
ItemAttachmentDeleting	Synchronous before event that occurs when a user removes an attachment from an item.
ItemCheckedIn	Asynchronous after event that occurs after an item is checked in.
ItemCheckedOut	Asynchronous after event that occurs after an item is checked out.
ItemCheckingIn	Synchronous before event that occurs as a file is being checked in.
ItemCheckingOut	Synchronous before event that occurs after an item is checked out.
ItemDeleted	Asynchronous after event that occurs after an existing item is completely deleted.
ItemDeleting	Synchronous before event that occurs before an existing item is completely deleted.
ItemFileConverted
ItemFileMoved	Occurs after a file is moved.
ItemFileMoving	Occurs when a file is being moved.
ItemUncheckedOut	Synchronous before event that occurs when an item is being unchecked out.
ItemUncheckingOut	Synchronous before event that occurs when an item is being unchecked out.
ItemUpdated	Asynchronous after event that occurs after an existing item is changed, for example, when the user changes data in one or more fields.
ItemUpdating	Synchronous before event that occurs when an existing item is changed, for example, when the user changes data in one or more fields.

 

Asynchronous vs Synchronous Events: The "ing" and the "ed"

As you may have noticed above, there are two events raised for each type of event. The "…ing" event occurs before the action starts and the "…ed" occurs after the actions ends. "…ing" events occur synchronously while the "…ed" events occur asynchronously. What does this mean?

Synchronous events:

• Occur before the event.
• Block the flow of code execution until your event handler completes.
• Provide you with the ability to cancel the events resulting in no after event (“…ed") being fired.

Asynchronous events:

• Occur after the event.
• Do not block the flow of code execution in SharePoint.

So what are some of the Best PRactices when building custom event handlers?  Here are a couple of things you want to keep in mind:

1. Security:

The assembly you deploy to the Global Assembly Cache(GAC) is running with full trust. Watch out for the following:

• Denial of Service attack: If a user uploads 10000 items to a list, what is the effect it will have to the systems your assembly uses.
• SQL Injection attack: If a user attempts to insert SQL statements into a column of a list that your assembly uses to update a database, what mechanisms are you using to make sure the input is valid.
• Cross Site scripting attack: What is the effect of adding script to a column that your assembly uses to update another area in SharePoint?

2. Performance:

Watch out for the following:

• Load: What burden are you placing on your web front end servers to run the assembly each time an event occurs? Use performance counters to determine this.
• Long Running Operations: Consider creating a custom SharePoint timer job. Kick off/ Schedule the Timer Job from the event rather than running all the logic inside the event. This will allow you to use the features of SharePoint to view whether the Timer Job ran successfully.
• Sync vs Async Events: Synchronous events have to wait until your code completes before returning the page, whereas Asynchronous events show the page immediately.

3. Error Handling:

When using synchronous events and you decide to cancel an event, let the user know why the event was cancelled. For example, update a Task List with a message why it failed.  Log your errors so that you can determine what issue is occurring when your system is in production environment.

4. Connections: Cater for external systems being down when you are trying to connect to them. Don’t let your code / solution go belly up because you cannot connect to a database.

5. Bulk Operations:

The MSDN documentation mentions that event handlers will not fire when bulk operation is occurring. For example, when a new list is created, the FieldAdding event will not fire.