SharePoint 2010 Feature Stapling (Part 2)

By: Shishir Bhandari | Comments | Related: > SharePoint Administration

Problem

To apply customizations to all team sites in your SharePoint instance and to automate them such that every new team site comes with your customization by default, you can use Feature Stapling. Read more about it in Part 1 of this article: SharePoint Feature Stapling - Part 1.

The SharePoint Feature Stapling concept is incomplete without understanding its lifecycle. In this sequel to 'SharePoint Feature Stapling - Part 1', we will learn about the lifecycle of Feature Stapling and the common issues surrounding it.

We will also discuss the advanced application of Feature Stapling for globally pushing your customizations to all SharePoint sites, irrespective of its site definition and for intentionally installing your custom site definition from this global push!

Solution

Feature Stapling starts creating issues when you try to customize any out of the box lists or list view webparts or pages.

For example, lets take the scenario of adding list view web parts (of "out of the box" lists) on the default.aspx page. (The same thing works when you do it manually after site creation.) You would think this is random but it is not. This happens because we aren’t aware of how list templates fit into the feature stapling lifecycle.

We would think that stapling feature code will execute after the site creation is over but this isn't the case. Lists are not created while our stapling feature code is running and that's why List view web parts throw an error or just fail. Let's look at it in detail.

If you open the site definition files, you will notice that the List Templates section is empty. Below is the snapshot of an STS or "Team Site" site definition.

This means that list templates are coming from somewhere else. Let's find out where?

As shown in the snapshot above, the Team Site (STS) uses the "TeamCollab" feature to deploy list templates. Now let's look at the sequence how these features are executed during site creation.

Lifecycle of Stapling Feature

As per the above figure, step 3 & 4 is your stapling feature trying to modify elements from the site definition (i.e. out of the box lists / list view web parts and Step 6 is when the actual lists from the site definition are getting created.

So you are trying to customize something which is not even available at that point of time. That's why, it fails!

Summary: If you are creating new lists, it will work but if you try to customize any lists that are part of the site definition that your stapling feature is associated with, it will fail.

What is the Solution for this?

One way is to remove the functionality (from the stapling feature) which needs to use out of the box lists or list view web parts. Put it in a feature and run it manually after site creation.
In case this operation has to be done on multiple sites and you need automation, you can write an application which will go through all the sites and do the required changes by activating your feature.
If it is a big deal and a lot of hassle to run this application every time new sites are created, you can write a timer job. Every time this timer job runs, it will check if your feature has been activated on sites. If not, it will activate your feature. To read more on Timer Jobs, refer to my blog on Custom SharePoint Timer Job
If your requirement is such that you are forced to do your customization in the stapling feature, then on a separate thread, keep checking if the site has been provisioned. If it is not provisioned, delay by using Thread.Sleep(). Once it is provisioned, run your customization code.
Use spweb.provisioned() property for checking if site provisioning is over. Sample code is shown below:

    while (true)
    {
    	using (SPWeb web = site.OpenWeb())
    	{
   
    		if (web.Provisioned)
    			break; //Get out of this loop and run <your Custom Code>
    		else
    		{
    			System.Threading.Thread.Sleep(5000);
    			continue;
    		}
    	}
    }
    //<Your Custom Code>

For reading more on spweb's provisioned () property, refer this msdn article.

How to globally push your customizations to all SharePoint sites irrespective of its site definition

The solution for activating your stapling feature on all sites, irrespective of its site definition, is to use TemplateName="GLOBAL"!

In the feature.xml of the stapling feature, associate it with the GLOBAL site definition as shown below:

<?xml version=" 1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint"/>
	<FeatureSiteTemplateAssociation Id=">Feature Gui<" TemplateName=<b>"GLOBAL"</b> />
</Elements>

Doing this will associate your stapling feature with all the site definitions which doesn't specify the AllowGlobalFeatureAssociations property in their webtemplate.xml. By default, all site definitions do not specify this property. So that's the good news and this solution will work!!!

Exception: Shared Services Provider site template and the Blank site template use the AllowGlobalFeatureAssociations ="FALSE" property.

This has been derived from this Microsoft support KB article.

How to intentionally prevent your Custom Site definition from this global push of your Customizations?

The solution for activating your stapling feature on all sites except for sites built from your custom site definition, is to set AllowGlobalFeatureAssociations property as FALSE.

If you set this property to FALSE, it will avoid binding with GLOBAL. As shown below, this property can be set in the webtemp.xml of the site definition.

So you have set AllowGlobalFeatureAssociations ="FALSE" in your custom site definition. This way you can activate your stapling feature on all sites except sites built from your custom site definition. To read more on this property, refer this msdn article.