Declarative provisioning of List Event Handlers in SharePoint 2013

When provisioning List Event Handlers you can choose either for the imperative or the declarative approach. And although there are many advantages to using the later, there are also a few things to take into account.

Separating code from configuration

Many of SharePoint configuration settings can be provisioned declaratively – using CAML (XML) and imperatively – through code. Although there are a few exceptions, in most scenarios similar results can be achieved using any of the approaches. Often it’s therefore the developer’s preference or the organization’s guidelines that determine which approach is being used.

Some developers prefer to use the imperative approach. Because every step of provisioning the configuration is written in code, they can debug it should things go wrong. This allows them to easier find the cause of the trouble and hopefully solve it faster.

Aside from the rich API SharePoint offers rich configuration capabilities using the Collaborative Application Markup Language (CAML). This XML-based language allows creating artifacts that contain instructions for configuring different pieces of SharePoint.

The biggest advantage of using CAML-based artifacts above code for provisioning configuration, is the fact, that XML provides better overview of the various configuration settings. Mixing configuration and code is not only difficult to read but also hard to maintain. Not to mention, that how the configuration is provisioned, depends a lot on the coding preferences of the particular developer. Declarative artifacts on the other hand have to comply to the strict and unambiguous syntax enforced by the XSD.

Even though declarative provisioning of SharePoint configuration offers clear advantages, it’s rarely the first choice approach for many SharePoint developers. The reason for that is in many scenarios the lack of documentation, ambiguous explanation of different elements and attributes and their functions and poor error logging that would help solve problems should any error occur during the provisioning process. Declaratively provisioning List Event Handlers is one of the areas where the SDK doesn’t provide sufficient explanation to make an effective use of this configuration provisioning capability.

Declarative provisioning of List Event Handlers in SharePoint 2013

In SharePoint 2013 List Event Handlers can be provisioned on different scopes. The deployment scope you choose, determines the configuration capabilities for provisioning List Event Handlers.

Provisioning Event Handlers using Site-scoped Features

List Event Handlers in SharePoint 2013 can be provisioned with Site- and Web-scoped Features. If you use a Site-scoped Feature, SharePoint will allow you to use the Scope**** attribute to specify on which scope your Event Handlers should be provisioned. If you choose the Site Scope, your Event Handlers will be provisioned to Lists in the whole Site Collection. If however you choose the Web Scope, Event Handlers will be provisioned only to Lists in the RootWeb.

One important thing to note, is that, no matter the scope and other attributes and configuration, all Event Handlers will apply to all Lists on the given Scope.

Provisioning Event Handlers using Web-scoped Features

When using a Web-scoped Feature some additional configuration options become available for provisioning List Event Handlers.

First, using the RootWebOnly attribute, you can specify that the configuration should be provisioned on the RootWeb only. Should the Feature be activated on a subweb an exception will be thrown.

Next, SharePoint will check the Receivers element for the presence of the ListTemplateId attribute. When found, SharePoint will additionally check for the ListUrl attribute. If both attributes are present, SharePoint will throw an exception as either the List Template ID or the URL but not both may be used. If the ListUrl is omitted, SharePoint will provision specified Event Handlers to all Lists of the given ID in the current Web. One thing to keep in mind in this process is that SharePoint uses only the number specified in the ListTemplateId attribute (which is equal to the SPList.BaseTemplate property) to retrieve the Lists which should receive the Event Handlers. Although in some other places the combination of List Template ID and the Feature ID are used, this is not the case here, so when creating List Definitions you should not rely on the combination of List Template ID and Feature ID being unique and should try to use unique List Template IDs instead.

If the ListTemplateId attribute is not specified, SharePoint will check for the presence of the ListUrl attribute. If present, SharePoint will provision the specified Event Handlers to the List at the given URL. It’s worth mentioning that the List URL is Web-relative (eg. Lists/MyList) and is made server-relative by SharePoint internally by calling the SPWeb.GetServerRelativeUrlFromUrl(ListUrl) method. If the ListUrl attribute is not specified SharePoint will provision the specified Event Handlers to all Lists in the Web on which the Feature has been activated.


In SharePoint 2013 most of the configuration can be provisioned both declaratively and imperatively. Although using the declarative approach is easier to keep overview of and maintain, is challenging to use due to little documentation. Declaratively provisioning List Event Handlers is one area that offers rich configuration capabilities but which are not clearly defined in the SDK. Knowing the configuration process makes it easier to use the declarative approach for provisioning List Event Handlers.