Overview
Microsoft Visual Studio 2010 provides a project type
that enables you to build event receivers that perform actions before or after
selected events on a Microsoft SharePoint 2010 site. Often, real SharePoint solutions need to catch
events and user actions to subsequently
execute some custom code.
Whenever you need to start business processes related to such
events and user actions, you
would probably need to develop custom workflows
However there are many situations in which a
workflow is overkill.
In such cases, it suffices to
execute a small piece of code that executes quickly and might not
always be critical to the
business. Suppose, for example, that you want to trigger an event
just after a document check-out
user action. In this situation, you can define a custom event
receiver that executes your
custom code whenever the check-out operation happens.
To satisfy these situations,
Microsoft SharePoint 2010 provides a standard way to develop
event receivers (known in early
SharePoint versions as event sinks), by inheriting from common
base classes and
registering the corresponding libraries into the target environment.
Event Receiver Targets
You
can create event receiver classes and override specific events by using visual
studio 2010 templates for SharePoint 2010. You can add event receivers for
following types of objects in SharePoint 2010:
§ List items
§ E-mails received by lists
§ Workflows attached to lists
§ List objects
§ Webs
§ Features
Item-Level Event
Receivers
The
events related to SPListItem instances are defined in classes that inherit from
SPItemEventReceiver.
The Events Provided
by the SPItemEventReceiver
Base Class
ItemAdded
Occurs after an item has been added to a list.
ItemAdding
Occurs before an item is going to be added to a list.
ItemAttachmentAdded
Occurs after an attachment has been added to a list item.
ItemAttachmentAdding
Occurs before an attachment is going to be added to a list item.
ItemAttachmentDeleted
Occurs after an attachment has been deleted from a list item.
ItemAttachmentDeleting
Occurs before an attachment is going to be deleted from a list item.
ItemCheckedIn
Occurs after an item has been checked into a list.
ItemCheckedOut
Occurs after an item has been checked out from a list.
ItemCheckingIn
Occurs before an item is going to be checked into a list.
ItemCheckingOut
Occurs before an item is going to be checked out from a list.
ItemDeleted
Occurs after an item has been deleted from a list.
ItemDeleting
Occurs before an item is going to be deleted from a list.
ItemFileConverted
Occurs after a file has been converted using document conversion
services.
ItemFileMoved
Occurs after an item has been moved.
ItemFileMoving
Occurs before an item is going to be moved.
ItemUncheckedOut
Occurs after an item has been unchecked out from a list.
ItemUncheckingOut
Occurs before an item is going to be unchecked out from a list.
ItemUpdated
Occurs after an item has been updated from a list.
ItemUpdating
Occurs before an item is going to be updated from a list.
ContextEvent The item received a context event.
The Main Members of
the SPEventPropertiesBase Class
EventType
Describes the kind of event that occurred, using a SPEventReceiverType event
type
enumeration.
EventUserToken
Corresponds to the current user token (SPUserToken) at the time the event is
fired.
OriginatingUserToken
Corresponds to the user token (SPUserToken) of the user that makes the
request.
Cancel
Boolean property with which you cancel the current event in Before events.
ErrorMessage
The error message that will be displayed to the end user if the event is
cancelled.
Status
Defines the status (SPEventReceiverStatus) of the current event. It can assume
values
of: Continue, to continue with the event; CancelNoError, to cancel the
event
without throwing any kind of error; CancelWithError, to cancel the
event
and throw an error; CancelWithRedirectUrl, to cancel the event and
redirect
the user to a specific RedirectUrl.
RedirectUrl
Defines the URL to redirect the user to, when the Status value is
CancelWithRedirectUrl.
SiteId
Returns the ID of the SPSite that contains the event source list item.
ReceiverData
Returns a String that represents the configuration of the current event
receiver
instance.
The members of the SPItemEventProperties implementation.
The Main Members of the SPItemEventProperties Class
InvalidateListItem
Invalidates (sets the corresponding variable to NULL) the list item that
represents
the
source of the event.
InvalidateWeb
Invalidates (sets the corresponding variables to NULL) the list item, the
list,
and the website that represent the source of the event. Internally, this
method
also disposes of the SPWeb instance related to the event, if any
such
instance exists.
OpenSite
Returns an instance of the SPSite that corresponds to the current event
source,
impersonating the current user at the time the event is fired, if any
user
is available; otherwise, it uses the current user.
OpenWeb
Returns an instance of the SPWeb corresponding to the current event
source,
impersonating the current user at the time the event is fired, if any
user
is available; otherwise, it uses the current user.
Dispose
Disposes the current SPSite and SPWeb instances. Internally, it also invokes
the InvalidateWeb
method.
CurrentUserId
Returns the ID of the user who caused the event to fire.
UserDisplayName
Returns the DisplayName of the user who caused the event to fire.
UserLoginName
Returns the LoginName of the user who caused the event to fire.
AfterProperties
References a hash table of tuples (String/Object) describing the properties
(columns)
of the source list item after the event occurred.
AfterUrl
Represents the URL of the source list item after the event occurred. For
item
file rename or move operations, this is the new file name.
BeforeProperties
References a hash table of tuples (String/Object) describing the properties
(columns)
of the source list item before the event occurred.
BeforeUrl
Represents the URL of the source list item before the event occurred. For
item
file rename or move operations, this is the old file name.
List Returns
a reference to the SPList that contains the event source list item.
ListId
Returns the ID of the list that contains the event source list item.
ListItem
Returns a reference to the SPListItem that represents the event source item.
ListItemId
Returns the ID of the event source item.
ListTitle
Returns the Title of the list that contains the event source list item.
Web Returns
a reference to the SPWeb that contains the event source item.
WebUrl
Returns the absolute URL of the SPWeb that contains the event source item.
RelativeWebUrl
Returns the server-relative URL of the SPWeb that contains the event
source
item.
Zone Returns
the Zone of the website that contains the event source list item.
Versionless
Provides the option to instruct SharePoint to handle the event without
List-Level Event
Receivers
Another
set of useful events are those related to lists. SharePoint offers a base class
named
SPListEventReceiver
with which you can trap changes to the fields of an existing list as well as
actions
related to adding or deleting lists instances.
FieldAdded
Occurs after a field has been added to a list definition.
FieldAdding
Occurs before a field is going to be added to a list definition.
FieldDeleted
Occurs after a field has been removed from a list definition.
FieldDeleting
Occurs before a field is going to be removed from a list definition.
FieldUpdated
Occurs after a field has been updated to a list definition.
FieldUpdating
Occurs before a field is going to be updated to a list definition.
ListAdded
Occurs after a new list has been added to a SPWeb instance.
ListAdding
Occurs before a new list is added to a SPWeb instance.
ListDeleted
Occurs after a list has been deleted from a SPWeb instance.
ListDeleting
Occurs before a list is deleted from a SPWeb instance.
As
with item-level events, all list-level events methods also receive a single
argument that
inherits
from SPEventPropertiesBase and represents the context of the event that will
occur
(Before)
or has occurred (After). For list-level events, the argument is a SPListEventProperties
type,
and provides the small set of members
InvalidateList
Invalidates (sets the corresponding variable to NULL) the list and/or the field
that
represents the source of the event.
InvalidateWeb
Invalidates (sets the corresponding variables to NULL) the list, the field, and
the
website that represent the source of the event. Internally, this method also
disposes
of the SPWeb instance related to the event, if any such instance exists.
Dispose
Disposes the current SPSite and SPWeb instances. Internally, it also invokes
the
InvalidateWeb
method.
FeatureId
Returns the GUID of the SharePoint feature that created the list instance for
ListAdding
and ListAdded event types.
FieldXml
Returns the XML definition of the field that is the source of the current
event.
List Returns
a reference to the SPList instance that is the source of the event.
ListId
Returns the ID of the SPList instance that is the source of the event.
ListTitle
Returns the Title of the SPList instance that is the source of the event.
TemplateId
Returns the ID of the list template that is related to the list instance that
is the
source
of the event.
UserDisplayName
Returns the DisplayName of the user who caused the event to fire.
UserLoginName
Returns the LoginName of the user who caused the event to fire.
Web Returns
a reference to the SPWeb that contains the event source list.
WebId Returns
a reference to the ID of the SPWeb that contains the event source list.
WebUrl
Returns the absolute URL of the SPWeb that contains the event source list.
Web-Level Event
Receivers
At the
web level, you can catch some events related to Site Collection deletion, both
before
and
after the action, and for website creation, deletion, moving, and provisioning.
To trap
such
events, you need to implement a custom class that inherits from SPWebEventReceiver.
.
The Events Provided
by the SPWebEventReceiver
Base Class
SiteDeleted
Occurs after a Site Collection has been deleted.
SiteDeleting
Occurs before a Site Collection is being deleted.
WebAdding
Occurs before an SPWeb is being added to a list collection.
WebDeleted
Occurs after an SPWeb has been removed from a Site Collection.
WebDeleting
Occurs before an SPWeb is going to be removed from a Site Collection.
WebMoved
Occurs after an SPWeb has been renamed or moved to another location.
WebMoving
Occurs before an SPWeb is being renamed or moved to another location.
WebProvisioned
Occurs after an SPWeb has been provisioned into a Site Collection.
Web-level
event receivers are usually most useful for enforcing custom policies, custom
layout
templates, or checking naming conventions, similar to list-events receivers.
Another
common use for web-level event receivers is to deny site or web deletion of
specific
websites—even
if the current user has the rights to provision and unprovision contents
and
sites. The unique argument for the web-level event receiver methods is of type
SPWebEventProperties,
which provides an entry point to the context Web, the context site,
and
their URLs.
The Main Members of
the SPWebEventProperties Class
InvalidateWeb
Invalidates (sets the corresponding variables to NULL) the website that
represents
the
source of the event. Internally, this method also disposes of the
SPWeb instance
related to the event, if any instance exists.
Dispose
Disposes of the current SPSite and SPWeb instances. Internally, it invokes the
InvalidateWeb
method.
FullUrl
Returns the absolute URL of the source Web on which the event occurred.
NewServerRelativeUrl
Represents the URL of the site after it has been moved.
ParentWebId
Returns the GUID of the current SPWeb instance.
ServerRelativeUrl
Represents the URL of the site before it has been moved.
UserDisplayName
Returns the DisplayName of the user who caused the event to fire.
UserLoginName
Returns the LoginName of the user who caused the event to fire.
Web Returns
a reference to the SPWeb that contains the event source list.
WebId Returns
a reference to the ID of the SPWeb that contains the event source
list.
Workflow Event
Receivers
SharePoint
provides workflow event receivers so that you can intercept events related to
running
workflows.
For instance, you can trap the WorkflowCompleted event to execute a custom
action
whenever a workflow instance completes
which
are provided by the base class, SPWorkflowEventReceiver.
The Events Provided
by the SPWorkflowEventReceiver Base Class
WorkflowCompleted
Occurs after a workflow instance is completed.
WorkflowPostponed
Occurs after a workflow instance has been postponed.
WorkflowStarted
Occurs after a workflow instance has been started.
WorkflowStarting
Occurs after a workflow instance is starting
The Main Members of
the SPWorkflowEventProperties Class
Member
Name Description
ActivationProperties
Represents the properties to start a new workflow instance. For example, it
contains
the InitiationData for the workflow. For further details about workflow
instances,
go to Part V, “Developing Workflows.”
AssociationData
Contains the workflow association data.
CompletionType
Contains information about the real outcome of the workflow. In fact, whenever
the
workflow completes, you can read the CompletionType property from
within
the WorkflowCompleted event. The property might have any of the following
values:
- Completed
- Errored
- ExternallyTerminated
- FailedOnStart
- InternallyTerminated
- NotApplicable
ErrorException
Returns the current exception instance, if defined.
InitiationData
Contains the workflow initiation data.
InstanceId
Represents the ID of the instance.
PostponedEvent
Signals whether the workflow has been postponed for Load or for Start.
RelativeWebUrl
Returns the relative URL of the SPWeb that contains the source.
TerminatedByUserId
The UserID of the user who terminated the workflow, for a terminated workflow
instance.
WebUrl
Returns the URL of the SPWeb that contains the source.
E-Mail Event
Receivers
The
e-mail event receivers support e-mail–enabled list instances, and allow you to
intercept
events
when the list receives e-mail messages. These event receivers are based on a
class
that inherits from SPEmailEventReceiver, and they
override the EmailReceived virtual method.
These events in event receiver classes are categorize
in to two categories. Those are before events and after events
Before events
Before events are synchronous events for which you can
write code, and have that code run before the operation that raised the event
has completed. The synchronous nature of before events, and the fact that the
operation has not yet completed, provides you with the ability to cancel the
event. By canceling an event, you can effectively cancel the operation that
raised the event. For example, you can cancel the adding, editing, or deleting
of a list item, and you can cancel the adding or deleting of a field in a list.
After events
After
events are asynchronous events for which you can write code, and have that code
run after the operation that raised the event has completed. The asynchronous
nature of after events, and the fact that the operation has already completed,
means that you cannot cancel the operation that raised the event; however, you
can be sure that all data changes associated with the event have completed when
your After-event handlers are raised.
In
this article I am going to discuss about how to create and deploy event
receiver for List item object using visual studio 2010.
Scenario
In this scenario, a secure sub site contains a list
named Job Definitions that
specifies allowed job titles for roles in the organization. Along with job
titles, the list also contains confidential salary information for the job
title and is therefore secured from users. In the main site, a list named Open Positions tracks
vacancies in the organization. You create two event receivers for the itemAdding and itemUpdating events
that verify that the title of the open position matches one of the approved
titles in the Job Definitions list.
Solution
Step 1: Create the Job Definitions sub site
1. On the main site, on the Site Actions menu,
click New Site
2. In the New Site dialog box, click Blank Site
3. On the right of the dialog box, click More Options
4. In the Title box, type Job Definitions
5. In the Web Site Address box, type JobDefinitions
6. In the Permissions section, click Use Unique Permissions, and then click Create
7. In the Visitors to this site section, select Use an existing group, and then selectHome Owners. Click OK.
Step 2: Create the Job Definitions list
1. In the New Site Select List from
left panel.
2. Then Click Create option to create a new List.
3. In the Create dialog box, Select Custom List.
4. In the Name box, type Job Definitions.
5. In the ribbon select List then Click Create Column.
6.Add
following columns to the list one by one, selecting given type within brackets.
§ Title (Default column)
§ MinSalary (Currency)
§ MaxSalar (Currency)
§ Role
Type (Choice: Permanent, Contract)
7.
Add few jobs to this list.
Note: The titles that you specify for each job that you
create because you will need them later.
Step 3:Create the Open Positions list
In the parent site, create a custom
list named Open Positions with the following columns:
Title (Default column)
Location (Single line of text)
Step 4: Create a SharePoint 2010 event receiver in
Visual Studio 2010
1.
Start Visual Studio 2010.
2On the File menu, click New, and then click Project
3. In the New Project dialog box, in the Installed Templates section, expand eitherVisual Basic or Visual C#, expand SharePoint, and then click 2010
4. In the template list, click Event Receiver
5. In the Name box, type VerifyJob
6. Leave other fields with their default values, and
click OK
7. In the What local site do you want to use for
debugging? List,
select your site.
8. Select the Deploy as a farm solution option, and then click Next
9. On the Choose Event Receiver Settings page, in the What type of event receiver do you want? List, select List Item Events
10. In the What Item should be the event source? List, select Custom List
11. Under Handle the following events select the An item is being added and the An item is being updated check boxes. Click Finish
Step 5: Add following constant variables to the event
receiver file.
private const string OpenPositionsListTitle = "Open Positions";
private const string TitleProperty = "Title";
private const string LoginName = @"SHAREPOINT\SYSTEM";
private const string JobDefinitionsListTitle = "Job Definitions";
private const string SubSiteName = "JobDefinitions";
private const string ErrorMessage = "The job you have entered is not defined in the Job Definitions List";
Step 6: Add a new method called checkItem to the event
receiver file.
Private bool checkItem(SPItemEventProperties properties)
{
string jobTitle = properties.AfterProperties[EventReceiver1.TitleProperty].ToString();
bool allowed = false;
SPWeb jobDefWeb = null;
SPList jobDefList;
SPUser privilegedAccount = properties.Web.AllUsers[EventReceiver1.LoginName];
SPUserToken privilegedToken = privilegedAccount.UserToken;
try
{
using (SPSite elevatedSite = new SPSite(properties.Web.Url, privilegedToken))
{
using (SPWeb elevatedWeb = elevatedSite.OpenWeb())
{
jobDefWeb = elevatedWeb.Webs[EventReceiver1.SubSiteName];
jobDefList = jobDefWeb.Lists[EventReceiver1.JobDefinitionsListTitle];
foreach (SPListItem item in jobDefList.Items)
{
if (item[EventReceiver1.TitleProperty].ToString() == jobTitle)
{
allowed = true;
break;
}
}
}
}
return (allowed);
}
finally
{
jobDefWeb.Dispose();
}
}
Step 7: Replace the ItemAdding method with the
following code.
public override void ItemAdding(SPItemEventProperties properties)
{
try
{
bool allowed = true;
if (properties.ListTitle == EventReceiver1.OpenPositionsListTitle)
{
allowed = checkItem(properties);
}
if (!allowed)
{
properties.Status = SPEventReceiverStatus.CancelWithError;
properties.ErrorMessage = EventReceiver1.ErrorMessage;
properties.Cancel = true;
}
}
catch (Exception ex)
{
properties.Status = SPEventReceiverStatus.CancelWithError;
properties.ErrorMessage = ex.Message;
properties.Cancel = true;
}
}
Step 8: Replace the ItemUpdating method with the
following code.
public override void ItemUpdating(SPItemEventProperties properties)
{
bool allowed = true;
if (properties.ListTitle == EventReceiver1.OpenPositionsListTitle)
{
allowed = checkItem(properties);
}
try
{
if (!allowed)
{
properties.Status = SPEventReceiverStatus.CancelWithError;
properties.ErrorMessage = EventReceiver1.ErrorMessage;
properties.Cancel = true;
}
}
catch (Exception ex)
{
properties.Status = SPEventReceiverStatus.CancelWithError;
properties.ErrorMessage = ex.Message;
properties.Cancel = true;
}
}
Step 9: Deploy the project.
1. In Solution Explorer, right-click
the project.
2. Then click Deploy
Step 10: Test the site
1. In the SharePoint site, in the Open Positions list,
click Add new item
2. In the Title field, provide a title for a job
description that does not exist in the Job Definitions list in the secured sub site.
3. Click Save You receive a message from the event
receiver.
4. In the Title field, provide a title for a job
description that exists in the Job Definitions list in the secured sub site.
5. Click Save. The position is created.
Enhancement
Once
you done all the steps above mention this is work perfectly. But if you add
another custom List to the same site, if you add a new item to that list, above
event receiver will execute but nothing will happen because of in the code we
check the list name before do anything.
But I want to make this event receiver execute only
for the Open Positions list.
To do this, you have to change few attributes in Elements.xml file
inside the event receiver.
Receivers element in the Elements.xml file look like this in your project
<Receivers ListTemplateId=“100“>
Do the changes to this element as follows to make your
event receiver to execute only when you do some changes to Open Positions list.
<Receivers ListUrl=“Lists/Open Positions“>
Hope this will help you......
