Sunday 3 June 2012

SharePoint 2010 : Event Receivers and their host types


SharePoint gives provision to developers for executing their custom code on many SharePoint actions/ events, e.g. feature activation/ deactivations, List item addition/ deletion etc. These are called as Event Receivers in SharePoint terminology.

Though it seems easy, I feel Event receivers are one of the most complex SharePoint artifacts to understand especially Event Host types.  Hence I decided to do some tutorials. This post talks about my findings as well as some basics.

Following SharePoint 2010 artifacts supports event receivers.
  1. Site collection
  2. Sub-site
  3. Feature
  4. List
  5. List site column
  6. List Item
  7. Workflow

Site Collection (SPSite) Events:

Event Method
Receiver base class
When
Nature
SiteDeleting
SPWebEventReceiver
Occurs when a site collection is being deleted.
Synchronous
SiteDeleted
SPWebEventReceiver
Occurs after a site collection has been deleted.
Synchronous/ Asynchronous

Subsite (SPWeb) Events :

Event Method
Receiver base class
When
Nature
WebAdding
SPWebEventReceiver
Occurs before a new subsite is created
Synchronous
WebProvisioned
SPWebEventReceiver
Fires after a subsite is fully provisioned and the provisioning process has stopped
Synchronous/ Asynchronous
WebDeleting
SPWebEventReceiver
Occurs before an existing Web site is completely deleted.
Synchronous
WebDeleted
SPWebEventReceiver
Occurs after an existing Web site is completely deleted.
Synchronous/ Asynchronous
WebMoving
SPWebEventReceiver
Occurs before an existing Web site has been renamed or moved to a different parent object
Synchronous
WebMoved
SPWebEventReceiver
Occurs after an existing Web site has been moved.
Synchronous/ Asynchronous

Notes:
  1. The Sub Site event receiver does not execute on root web site of the site collection.
  2. Event can be hosted by either individual subsite or whole site collection. It is controlled by scope of the feature who is registering the event and Scope attribute of the Receivers element.
Figure 1 : Receivers Element Scope attribute


List (SPList) Events:

Event Method
Receiver base class
When
Nature
ListAdding
SPListEventReceiver
Occurs before a list is created on a website
Synchronous
ListAdded
SPListEventReceiver
Raised after a list is added to a website
Synchronous/ Asynchronous
ListDeleting
SPListEventReceiver
Raised before a list is deleted.
Synchronous
ListDeleted
SPListEventReceiver
Occurs after a list is deleted.
Synchronous/ Asynchronous
EmailReceived
SPEmailEventReceiver

Provides a method for trapping the event when a list receives an e-mail message
Synchronous/ Asynchronous

Notes:
Event can be hosted by either individual subsite or whole site collection. It is controlled by scope of the feature who is registering the event and Scope attribute of the Receivers element. Please see the figure 1.

List Field (SPField) Events:

Event Method
Receiver base class
When
Nature
FieldAdding
SPListEventReceiver
Occurs before a field link is added to a content type, or field is added to a list.
Synchronous
FieldAdded
SPListEventReceiver
Occurs after a field link is added or after field is added to a list.
Synchronous/ Asynchronous
FieldDeleting
SPListEventReceiver
Occurs before a field is removed from the list
Synchronous
FieldDeleted
SPListEventReceiver
Occurs after a field link has been removed from the content type or field has been removed from the list
Synchronous/ Asynchronous
FieldUpdating
SPListEventReceiver
Occurs before a field link is updated or field is updated in list
Synchronous
FieldUpdated
SPListEventReceiver
Occurs after a field link has been updated or field is updated in list
Synchronous/ Asynchronous

List Item (SPListItem) Events:

Event Method
Receiver base class
When
Nature
ItemAdding
SPItemEventReceiver
Occurs before an item is added
Synchronous
ItemAdded
SPItemEventReceiver
Occurs after an item is added
Synchronous/
Asynchronous
ItemDeleting
SPItemEventReceiver
Occurs before an item is deleted
Synchronous
ItemDeleted
SPItemEventReceiver
Occurs after an item is deleted
Asynchronous
ItemUpdating
SPItemEventReceiver
Occurs before an item is changed
Synchronous
ItemUpdated
SPItemEventReceiver
Occurs after an item is changed
Synchronous/ Asynchronous
ItemFileConverted
SPItemEventReceiver
Occurs after a file in a document library is converted from one type to another
Synchronous/ Asynchronous
ItemFileMoving
SPItemEventReceiver
Occurs before a file is moved
Synchronous
ItemFileMoved
SPItemEventReceiver
Occurs after a file is moved
Synchronous/ Asynchronous
ItemCheckingIn
SPItemEventReceiver
Occurs before an item is checked in
Synchronous
ItemCheckedIn
SPItemEventReceiver
Occurs after an item is checked in
Synchronous/ Asynchronous
ItemCheckingOut
SPItemEventReceiver
Occurs before an item is checked out
Synchronous
ItemCheckedOut
SPItemEventReceiver
Occurs after an item is checked out
Synchronous/ Asynchronous
ItemAttachmentAdding
SPItemEventReceiver
Occurs before an attachment is added to an item
Synchronous
ItemAttachmentAdded
SPItemEventReceiver
Occurs after an attachment is added to an item
Synchronous/ Asynchronous
ItemAttachmentDeleting
SPItemEventReceiver
Occurs before an attachment is removed from an item
Synchronous
ItemAttachmentDeleted
SPItemEventReceiver
Occurs after an attachment is removed from an item
Synchronous/ Asynchronous


Workflow Events:

Event Method
Receiver base class
When
Nature
WorkflowStarting
SPWorkflowEventReceiver
Occurs before a workflow is created
Synchronous
WorkflowStarted
SPWorkflowEventReceiver
Fires once workflow is started
Synchronous/ Asynchronous
WorkflowPostponed
SPWorkflowEventReceiver
Raised when the workflow is postponed, which happens the farm is too busy handling other workflows.
Synchronous/ Asynchronous
WorkflowCompleted
SPWorkflowEventReceiver
Occurs after an existing Web site is completely deleted.
Synchronous/ Asynchronous

Important Notes for List, List field, list item and workflow events:
  1. Event can be hosted by Site Collection, individual subsite, List templates, List instances, Content Type. It is controlled by scope of the feature who is registering the event and Scope attribute of the Receivers element. Please see the figure 1.
  2. Event can be registered to the list using <Receivers> tag by two ways.
    1. Attaching to the list template using  <Receivers ListTemplateId="" >
    2. Attaching to the list instance using <Receivers ListUrl="" >
  3. Events can be registered to the content type by copying the Receiver tag into the XmlDocuments tag. Event receivers can be registered to both site content type (element.xml) or list content type (list schema.xml)

Feature Events:

Event Method
Receiver base class
When
Nature
FeatureActivated
SPFeatureReceiver
Raised after a feature has been activated
Asynchronous
FeatureDeactivating
SPFeatureReceiver
Raised before a feature is deactivated
Synchronous
FeatureInstalled
SPFeatureReceiver
Raised after a feature has been installed
Asynchronous
FeatureUninstalling
SPFeatureReceiver
Raised before a feature is uninstalled
Synchronous
FeatureUpgrading
SPFeatureReceiver
Raised when a feature is upgrading
Synchronous

Notes:
Nothing explains Feature Upgrade event receiver better than Chris O’Brien’s post http://www.sharepointnutsandbolts.com/2010/06/feature-upgrade-part-1-fundamentals.html.

Ways to Attach Event Receivers:
  • Declarative Way (element.xml)
    In this approach, event receivers are registered using element manifest files. This approach works in Sandbox solution as well.
  • Programmatic way
    In this way, event receivers are created programmatically, ideally in feature receiver code.

You can download my tutorial having many examples of all kind of event receivers with different host types here.

Below, I have explained the tutorial code with help of screenshots taken using SharePoint Manager 2010. For testing purposes, I created a Site Collection named as SharePoint Custom Development and a sub-site named as SubSite.

1.   SPSiteEventReceivers
Shows how to create site collection event receivers.


<!--The Project item should be associated with a feature scoped at site collection.-->
  <Receivers >
      <Receiver>
        <Name>SPSiteEventReceiversSiteDeleting</Name>
        <Type>SiteDeleting</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.SPSiteEventReceivers.SPSiteEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
      <Receiver>
        <Name>SPSiteEventReceiversSiteDeleted</Name>
        <Type>SiteDeleted</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.SPSiteEventReceivers.SPSiteEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
  </Receivers>

2.    SiteCollectionScopedSPWebEventReceivers:
These are the sub-site event receivers hosted by site collection.

  
<!-- The parent feature scope is 'Site'. The host of these events will be site collection due to 
  Receivers tag Scope='Site' attribute. 
  Hence these events will be bound to every subsite within the site collection except RootWeb-->
  <Receivers Scope="Site" >
      <Receiver>
        <Name>SiteCollectionScopedSPWebEventReceiversWebDeleting</Name>
        <Type>WebDeleting</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.SiteCollectionScopedSPWebEventReceivers.SiteCollectionScopedSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
      <Receiver>
        <Name>SiteCollectionScopedSPWebEventReceiversWebMoving</Name>
        <Type>WebMoving</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.SiteCollectionScopedSPWebEventReceivers.SiteCollectionScopedSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
      <Receiver>
        <Name>SiteCollectionScopedSPWebEventReceiversWebAdding</Name>
        <Type>WebAdding</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.SiteCollectionScopedSPWebEventReceivers.SiteCollectionScopedSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
  </Receivers>

  • Host type of both above event receivers is Site Collection. Hence when seen in the Event Receiver collection of Site collection, it look like this.

Figure 2 : Site collection and sub-site events hosted by Site Collection



3.    IndividualSubSiteSPWebEventReceivers
These sub site event receivers are hosted by individual sub site.

  <!--
  These events will be bound to the subsites in which parent feature is activated because.
   1. The parent feature scope is 'Web'. 
   2. Scope='Web' attribute of Receivers tag. 
  -->
  
  <Receivers Scope="Web" >
      <Receiver>
        <Name>IndividualSubSiteSPWebEventReceiversWebDeleted</Name>
        <Type>WebDeleted</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.IndividualSubSiteSPWebEventReceivers.IndividualSubSiteSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
      <Receiver>
        <Name>IndividualSubSiteSPWebEventReceiversWebMoved</Name>
        <Type>WebMoved</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.IndividualSubSiteSPWebEventReceivers.IndividualSubSiteSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
      <Receiver>
        <Name>IndividualSubSiteSPWebEventReceiversWebProvisioned</Name>
        <Type>WebProvisioned</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.IndividualSubSiteSPWebEventReceivers.IndividualSubSiteSPWebEventReceivers</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
  </Receivers>

Figure 3 : Sub-site Event hosted by sub site


4.    ListTemplateEventReceiver
  • This event receiver is associated with Announcement List Template. All list created through Announcement list template will have this event receiver attached.


  <!--
 ListTemplateId attribute is used to attach the ItemAdded event to Announcement list template.
  As the parent feature scope 'Web', the host type of this event will be individual subsite in which 
  parent feature is activated.
   -->
  <Receivers ListTemplateId="104">
      <Receiver>
        <Name>ListTemplateEventReceiverItemAdded</Name>
        <Type>ItemAdded</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.ListTemplateEventReceiver.ListTemplateEventReceiver</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
  </Receivers>


Figure 4 : Parent feature plays role in deciding the Host


5.    IndividualListEventReceiver
This event receiver is attached to the Test Events List created declaratively.


  <!--
ListUrl attribute is used to attach the ItemAdded event to "Test Events List" list created in this project.-->
  <Receivers ListUrl="Lists/Test Events List">
      <Receiver>
        <Name>IndividualListEventReceiverItemAdded</Name>
        <Type>ItemAdded</Type>
        <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
        <Class>EventReceivers.IndividualListEventReceiver.IndividualListEventReceiver</Class>
        <SequenceNumber>10000</SequenceNumber>
      </Receiver>
  </Receivers>


6.    ContentTypeEventReceiver
This shows how to associate event receiver to a content type.


<!--
Parent ContentType: Announcement (0x0104). Note that without "Inherits='false'",
event receiver does not get attached to the content type. This is due to a known bug in SharePoint 2010. -->
  <ContentType ID="0x010400069AB2346B6241699E565C8E004F2F4E"
               Name="Custom Announcement"
               Group="Custom Content Types"
               Description="This CT is created to demonstrate the association of event receivers."
               Inherits="false"
               Overwrite="TRUE"
               Version="0">
    <FieldRefs>
              <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Name="Title"/>
    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/events">
        <Receivers xmlns:spe="http://schemas.microsoft.com/sharepoint/events">
          <Receiver>
            <Name>ContentTypeEventReceiver</Name>
            <Type>ItemAdded</Type>
            <SequenceNumber>10000</SequenceNumber>
            <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
            <Class>$SharePoint.Type.a3dac829-4c36-46a9-930c-55698372b050.FullName$</Class>
            <Data></Data>
            <Filter></Filter>
          </Receiver>
        </Receivers>
      </XmlDocument>
    </XmlDocuments>
  </ContentType>


Figure 5 : Attach event receiver to content type

7.    WorkflowEventReceivers
  • This example shows how to attach the workflow event receivers to list template and individual list.


<!--Workflow events will be attached to the Links list template.
VS 2010 asks for selecting the list template id by default.
But by changing the ListUrl attribute, events can be attached to individual list too.
-->
<Receivers ListTemplateId="103">
       <Receiver>
              <Name>WorkflowEventReceiversWorkflowStarting</Name>
              <Type>WorkflowStarting</Type>
              <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
              <Class>EventReceivers.WorkflowEventReceivers.WorkflowEventReceivers</Class>
              <SequenceNumber>10000</SequenceNumber>
       </Receiver>
</Receivers>
<Receivers ListUrl="Lists/Links">
       <Receiver>
              <Name>WorkflowEventReceiversWorkflowCompleted</Name>
              <Type>WorkflowCompleted</Type>
              <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
              <Class>EventReceivers.WorkflowEventReceivers.WorkflowEventReceivers</Class>
              <SequenceNumber>10000</SequenceNumber>
       </Receiver>
</Receivers>



Figure 6 : Workflow event receivers


8.    Programmatically creating Event receivers :
The below code shows how to register/ remove the event receiver through feature receiver .


public class EventReceiverAssociatorEventReceiver : SPFeatureReceiver
    {
        public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            SPWeb web = properties.Feature.Parent as SPWeb;
            if (web != null)
            {
                SPList list = web.Lists.TryGetList("Object Model Event Receivers");

                if (list == null)
                {
                    Guid listGUID = web.Lists.Add("Object Model Event Receivers",
                                                  "Created for testing programmatic association of event receivers.",
                                                  SPListTemplateType.GenericList);
                    list = web.Lists[listGUID];
                }

                AddEventReceiverToList("EventReceivers.ProgrammaticallyAddedEventReceiver.ProgrammaticallyAddedEventReceiver",
                                        list,
                                        "EventReceivers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f3155a6cff2154bb",
                                        SPEventReceiverType.ItemAdded,
                                        SPEventReceiverSynchronization.Asynchronous);
            }
        }

        public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
        {
            SPWeb web = properties.Feature.Parent as SPWeb;
            if (web != null)
            {
                SPList list = web.Lists.TryGetList("Object Model Event Receivers");

                if (list != null)
                {
                    foreach (SPEventReceiverDefinition eventreceiverDef in list.EventReceivers)
                    {
                        if (eventreceiverDef.Assembly == "EventReceivers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f3155a6cff2154bb"
                            && eventreceiverDef.Type == SPEventReceiverType.ItemAdded)
                        {
                            eventreceiverDef.Delete();
                            break;
                        }
                    }
                }
            }
        }

        protected static void AddEventReceiverToList(string className, SPList list, string assemblyName, SPEventReceiverType eventReceiverType, SPEventReceiverSynchronization eventReceiverSynchronization)
        {
            if (className == null) throw new ArgumentNullException("Class name cannot be null.");
            if (list == null) throw new ArgumentNullException("List cannot be null.");
            if (assemblyName == null) throw new ArgumentNullException("Assembly name cannot be null.");
            SPEventReceiverDefinition eventReceiver = list.EventReceivers.Add();
            eventReceiver.Class = className;
            eventReceiver.Assembly = assemblyName;
            eventReceiver.Type = eventReceiverType;
            eventReceiver.Synchronization = eventReceiverSynchronization;
            eventReceiver.Update();
        }
    }




Updated (11/7/2012):
While using BIN deployment in one of my projects, I observed that the feature with event receivers throws File Not Found error and does not get activated. After googling, I came to know that this behavior is by design. SharePoint 2010 does not support Event receivers. I also observed that event receiver feature gets activated when I added Unrestricted="true" to the NamedPermissionSet into the custom CAS Policy config file present in the SharePointRoot\CONFIG folder. Unfortunately this change is not recommended due to security reasons. So only way to fix this is to change the Deployment target to GAC instead of BIN.

Few Key take ways and findings:
  1. Feature scope plays role in deciding the event receiver host object
  2. Host type also can be controlled through Receivers tag Scope attribute .
  3. Sandbox solution does not allow event receivers to be attached programmatically.
  4. Declaratively event receivers can be attached to individual list using ListUrl attribute of Receivers tag.

6 comments:

  1. Hi,

    your research about Event Handler is awesome. One thing that wasn't clear for me is that "ListTemplateId" or "ListUrl" requires the scope "Web".
    If you use it with scope "Site" the Event Handler isn't limited to the Type or Url.

    Thanks for your detailed work,
    Andreas

    ReplyDelete
    Replies
    1. Hi Andreas,

      Thanks for comments! "ListTemplateId" or "ListUrl" aren't limited to "Web" scope. "Site" scope will also work. Am I sounding somwhere whether it is limited to "Web" scope? You can see in examples I have not mentioned scope which is "Site" by default. Plz let me know.

      ~Parwej

      Delete
  2. Hi Parwej,
    this is a great piece of work and I only wish I had come across this earlier. I'm trying to deploy a sandbox solution that includes event handlers on document sets and am having issues with not being able to create the welcomepage. I know you said in findings above that you can't programmatically attach event handlers, is there any other way for document sets???

    ReplyDelete
    Replies
    1. Hi jjones,

      Apologies for late reply and thanks for comment. I am thinking that you are creating the document set decoratively. I would suggest to create the document set first through browser. Then attach event receiver to it through VS. You can use farm solution for it. Once this is done, then you can save the site as template. Get the wsp created and import it into VS. Then you can find the declarative code with event receiver and welcome page together which you can use. May be going through by blog http://parwejpathan.blogspot.in/2012/05/sharepoint-2010-create-custom-document.html will help.

      Thanks,
      Parwej

      Delete
  3. Very nice post thanks for sharing this p

    ReplyDelete