Feature Stapling Lifecycle

The actual lifecycle of the feature stapling process is not documented actually documented anywhere. The following information has been solely gathered based on my testing and experimenting with the process.

If we step back and look at a site definition file we know that the GLOBAL#0 site template is applied to all site definitions. Many of the Microsoft provided site definitions enable functionality through the use of the feature system. If you open up the STS site definition ONET.XML file, you will see two sections near the bottom called SiteFeatures and WebFeatures:

You will notice that in many of the Windows SharePoint Services site definition files the ListTemplates section is not populated with anything; they use list definition features instead. As you can see, the Team Site site definition points to a feature called TeamCollab. This feature makes list definitions available to the web that is being created.

So what does this all mean when it comes to feature association? The important thing to remember here is that any feature receivers you develop and associate to a site definition will get executed before any of the lists on that site have been provisioned. However, anything provisioned via the Global Site Definition will be available to your feature receiver.

This is not a problem if you simply want to create new lists, libraries, etc. However, if you are attempting to manipulate any lists that are part of the site definition you are associating with you will find yourself looking at a System.ArgumentException stating “Value does not fall within the expected ranged.”

The following image shows what happens when I create a Team Site that has my custom feature receiver associated to it:

Solution

We have already determined that feature receivers make it extremely easy for a developer to extend and customize out of the box site definitions without touching the files. But we run into a road block when we attempt to customize the lists and libraries that are part of that site definition.

One way I have used to get around this is to simply delay the customizations until after the site has completely provisioned.

The following is an example using the ThreadPool.QueueUserWorkItem method:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
    using (SPWeb web = (SPWeb)properties.Feature.Parent)
    {
        ThreadPool.QueueUserWorkItem(new WaitCallback(RunProcess), web.Url);
    }
} 
 
private void RunProcess(object state)
{
    Thread.Sleep(5000); 
 
    string url = (string)state;
    using (SPSite site = new SPSite(url))
    {
        using (SPWeb web = site.OpenWeb())
        {
            // at this point, the site should be provisioned
            // and we will now have access to all lists on it
            SPList list = web.Lists["Shared Documents"];
            list.Description = "Updated from Feature Receiver";
            list.Update(); 
 
        }
    }
}

Why are we running on a different thread? Well, this allows the site provisioning process to complete and then we come back in a few seconds later to customize it as needed. Of course, the sample above is not 100% perfect. What happens if it takes 10 seconds to provision a site – well the method above would fail out.

A more elegant way would probably be to check the SPWeb.Provisioned property which is False until after the provisioning process has completed; but you get the general idea.

Summary

Hopefully this two part series has given you the necessary information needed to get started using SharePoint Feature Stapling and what potential issues to watch out for. There is many resources out on the Internet that cover other aspects of Feature Stapling, but I’ll list a few here for your reference:

MSDN: Feature Stapling

MSDN: Feature Event Receiver

http://blogs.msdn.com/cjohnson/archive/2006/11/01/feature-stapling-in-wss-v3.aspx

http://www.sharepointnutsandbolts.com/2007/05/feature-stapling.html