Working with Event Handlers in

SharePoint 2007
Dallas SharePoint Developers Group
8 October 2008
Miguel Wood, TekFocus
 Introducing Event Handlers
• An event handler is a Microsoft® .NET assembly
containing one or more classes handling events that
are triggered by Microsoft® SharePoint® Products and
Technologies Avoid deletion of task when
not completed yet

Audit any change that

occurs to task

Start custom processing

when priority is changed to
High

Prevent the deletion of a

column for this list
 What Type of Events?
• Events triggered for lists, document libraries, content
types, and sites
• Events supported for incoming e-mail messages
• Support for synchronous events and asynchronous events
– Synchronous events occur before the fact and are cancelable
• Events are used in other scenarios
– Custom policies
– Features
 Scope of Events
Scope Description Base Class
Item in a list or Actions users can do in a list include adding, SPItemEventReceiver
library modifying, deleting, check-in and check-out, ...

List or library Trap changes to entities of list schema events, SPListEventReceiver

supporting list schema operations and the addition or
removal of content types.

Web Events fired at the level of the site (e.g. adding and SPWebEventReceiver
removing sites)
Email Provides a method for trapping the event when a list SPEmailEventReceiver
receives an e-mail message (EmailReceived)

Feature Trap the activation, deactivation, installation, or SPFeatureReceiver

uninstalling of a Feature
 Synchronous vs. Asynchronous Events
• Synchronous events end at –ing
– E.g. ItemDeleting
– Event handler code executed BEFORE action committed
– Windows® SharePoint® Services 3.0 waits before your code returns
– Option to cancel the action and return error message
• Asynchronous events end at –ed
– E.g. ItemDeleted
– Event handler code executed AFTER action committed
– Executed in its own worker thread
– Windows SharePoint Services 3.0 does not wait for the return of your code
 Development Steps
• Create Class Library
– Microsoft® Visual Studio® extensions for Widows
SharePoint Services (VSeWSS) provide an item
template for event receiver classes
• Inherit from one of the base classes
• Implement one of the event handlers
• Register the event handler
– VSeWSS by default register using Feature
– Programmatically target one instance
 Why an Event Handler?

Complex Data Validation (prior to edits being saved)

Filling fields (columns) with external system data or complex calculations

Logging events to external systems (file system, custom database, etc.)

Sending confirmation emails

 SharePoint 2003 v. SharePoint 2007 Event
Handlers

In SharePoint 2003, event handlers were often used for simple workflow
applications for document or form libraries (the only list types that supported event
handling in SharePoint 2003).

In SharePoint 2007, Windows Workflow Foundation (WF) from the .NET 3.0
framework is used for creating both sequential and state machine workflows. You
should avoid creating highly complex event handlers in SharePoint 2007. As a
general rule, if your event handler must perform more than one or two operations,
you should consider using a workflow rather than an event handler.
 Workflow or an Event Handler?

Workflows Event Handlers

●
Are most appropriate for long- ●
Respond in near real-time to
running processes that may user-initiated actions on a list
span minutes, hours, or days, ●
Could be used to piece
and involved many individuals together workflows
(actors) ●
Very simple workflows may be
●
Could be used to respond to easier to implement as an
list events in real time event handler
 Event Handler Basics in
SharePoint 2007

Support for all list types

●
Synchronous event handlers fire before an event is processed by SharePoint (e.g. ItemUpdating)
●
Asynchronous event handlers fire after an event is processed by SharePoint (e.g. ItemUpdated)

More events supported

Two types of events exposed

SPEventReceiver Class Hierarchy

System.Object

Windows SharePoint Services

.NET Assembly

Microsoft.SharePoint.
SPEventReceiverBase
SPEventProperties Class Hierarchy

System.Object

Windows SharePoint Services

Microsoft.SharePoint.
.NET Assembly
SPEventPropertiesBase

Microsoft.SharePoint. Microsoft.SharePoint. Microsoft.SharePoint.

SPWebEventProperties SPListEventProperties SPItemEventProperties
 Key EventReceiver Public Methods

SPWebEventReceiver SPListEventReceiver SPItemEventReceiver

ItemAdded
●
ItemAdded
●

ItemAdding
●
ItemAdding
●

●
SiteDeleted ●
FieldAdded ItemAttachmentAdded
●
ItemAttachmentAdded
●

ItemAttachmentAdding
●
ItemAttachmentAdding
●

ItemAttachmentDeleted
●
ItemAttachmentDeleted
SiteDeleting FieldAdding
●

● ● ItemAttachmentDeleting
●
ItemAttachmentDeleting
●

ItemCheckedIn
●
ItemCheckedIn
●

ItemCheckedOut
WebDeleted FieldDeleted
●

● ● ItemCheckedOut
●

ItemCheckingIn
●
ItemCheckingIn
●

ItemCheckingOut
●
ItemCheckingOut
●

WebDeleting FieldDeleting ItemDeleted

●
● ● ItemDeleted
●

ItemDeleting
●
ItemDeleting
●

ItemFileConverted
●
ItemFileConverted
●

●
WebMoved ●
FieldUpdated ItemFileMoved
●
ItemFileMoved
●

ItemFileMoving
●
ItemFileMoving
●

ItemUncheckedOut
●
ItemUncheckedOut
●

●
WebMoving ●
FieldUpdating ItemUncheckingOut
●
ItemUncheckingOut
●

ItemUpdated
●
ItemUpdated
●

ItemUpdating
●
ItemUpdating
●
 EventProperties Class Properties

SPWebEventProperties SPListEventProperties SPItemEventProperties

●
●Cancel
●
●Cancel ●
ErrorMessage
AfterProperties
●
AfterProperties
●

AfterUrl
●
●
AfterUrl
●

●ErrorMessage
●
BeforeProperties
●
●EventType BeforeProperties
● ●

BeforeUrl
●
BeforeUrl
●

●EventType
● ●Field
●
Cancel
●
Cancel
●

●FieldName Context
●FullUrl
● ●
● Context
●

●FieldXml
● CurrentUserId
●
CurrentUserId
●

●NewServerRelativeUrl
● ErrorMessage
●
ErrorMessage
●

●List
●
EventType
●
EventType
●

●ReceiverData
●
ListId
●ListId
●
●
ListId
●

ListItem
●
ListItem
●ServerRelativeUrl
●
● ●ListTitle
●
ListItemId
●
ListItemId
●

●RecieverData
●
ListTitle
●SiteId
●
● ListTitle
●

●SiteId
● ReceiverData
●
ReceiverData
●

●Status
● RelativeWebUrl
●
RelativeWebUrl
●

●Status
●
SiteId
●
SiteId
●

●UserDisplayName
●
●UserDisplayName
●
Status
●
Status
●

UserDisplayName
●

●UserLoginName ●UserLoginName UserDisplayName

● ●
●
UserLoginName
●
UserLoginName
●

●Web
●
●Web Versionless
●
● Versionless
●

●WebId
● WebUrl
●
WebUrl
●

●WebId
●
Zone
●

●WebUrl
● Zone
●
 Feature Receivers
• Events are triggered when a Feature is
– Installed
– Uninstalled
– Activated public class FeatureReceiver : SPFeatureReceiver
{
– Deactivated public override void FeatureInstalled
(SPFeatureReceiverProperties properties) {}
public override void FeatureUninstalling
(SPFeatureReceiverProperties properties) {}
public override void FeatureActivated
(SPFeatureReceiverProperties properties) {}
public override void FeatureDeactivating
(SPFeatureReceiverProperties properties) {}
}
Demo

CREATING A CALCULATED FIELD BY

USING AN EVENT HANDLER
 Process Flow
Start setFields()

Get handle
to list item
that raised
the event Yes Set Notes
field to
current
date/time
Calculate the
extended price
Set
Approver
based on
ext price
Extended price amount
> 5,000 ?

Update the
list item
No fields based
on business
rules

End setFields()
Demo

PREVENTING DELETION BY USING

AN EVENT HANDLER
Process Flow
Start deleteItem()

Get handle
to item to
be deleted

Get
properties
of user
requesting
deletion

Cancel deletion
and display
Can task be message
No indicating why task
deleted?
can’t be deleted

Yes

End deleteItem()
 Resources
• Visual Studio Extensions for Windows SharePoint Services, v1.1 (
www.microsoft.com/downloads/details.aspx?FamilyID
=3E1DCCCD-1CCA-433A-BB4D-97B96BF7AB63&displaylang=en)
• Windows SharePoint Services 3.0 SP1 Developer Evaluation Image (
www.microsoft.com/downloads/details.aspx?FamilyID
=1beeac6f-2ea1-4769-9948-74a74bd604fa&DisplayLang=en)
• Application Development Exams
– 70-541 TS: Windows SharePoint Services 3.0 (
www.microsoft.com/learning/exams/70-541.mspx)
70-542 TS: Microsoft® Office SharePoint® Server 2007 (
www.microsoft.com/learning/exams/70-542.mspx)