Feature Stapling and the FeatureActivated Event in Windows SharePoint Services 3.0
Summary: Feature stapling is a concept that allows you to attach (or staple) a SharePoint Feature to a SharePoint site definition without modifying the original site definition files in any way. Learn how to use Feature stapling in conjunction with the FeatureActivated(SPFeatureReceiverProperties) event and how to avoid some of the issues that can arise when using this particular method of customizing sites. (7 printed pages)
Joel Krist, iSoftStone
February 2010
Applies to: Windows SharePoint Services 3.0, Microsoft Office SharePoint Server 2007
Contents
SharePoint Features
Feature Stapling
Feature Stapling and the FeatureActivated Event
Sample Code
Automatically Activating Stapled Features
Conclusion
Additional Resources
SharePoint Features
A Windows SharePoint Services 3.0 Feature is a package of SharePoint elements that can be deployed and activated at a specific scope, allowing you to customize your SharePoint sites. Some examples of SharePoint elements that can be packaged as Features include:
Web Parts
Workflows
List templates
List instances
Menu items
For more information about SharePoint Features, see Working with Features.
A SharePoint Feature can be deployed with a custom SharePoint site definition by modifying the site definition's Onet file and adding the needed Feature elements. New sites and site collections that are created from the site definition automatically have the feature installed at the specified scope.
Modification to the Onet.xml file works fine when you are applying changes to a custom site definition. However, this approach cannot be used on a default site definition, because any changes you make to a default site definition can be overwritten if an upgrade is performed. For this reason, modifications to default site definitions are not recommended or supported. However, there is a another way that you can customize default site definitions to include additional Features without touching the site definition file itself. This technique is called Feature Stapling.
Feature Stapling
Feature stapling allows you to create another Feature that defines the association of your Feature and the site definition you want to staple it to, in such a way that the original site definition is not modified. This technique allows the new Feature to be associated with the site definition and that association will survive product upgrades.
Feature stapling is performed by creating a separate Feature that makes use of one or more FeatureSiteTemplateAssociation elements. This element specifies the association between a Feature and a site definition, so that when sites are provisioned from a site definition, the associated Features are automatically activated.
Feature Stapling and the FeatureActivated Event
Feature event receivers allow custom code to be executed in response to the installation, activation, and deactivation of a Feature. The event receiver for a Feature is specified with the ReceiverAssembly and ReceiverClass properties in the Feature.xml file of that Feature. A Feature receiver can override the SPFeatureReceiver.FeatureActivated method to hook the feature activation event, allowing custom code to run and perform a variety of tasks.
Because of the way that events are ordered during site creation, it is possible that site elements that are required by a stapled Feature's event receiver will not have been provisioned yet. You need to know when your Feature will be executed during the site provisioning process. Whenever a site is created, the following events occur:
Feature event receiver is installed.
Site or site collection is provisioned from the site definition file.
Feature's event receiver activation method is called.
Elements of a Feature that are associated with the site definition are provisioned.
Steps 3 and 4 are repeated for each Feature in the site definition.
Elements from the site definition are provisioned.
Imagine a situation in which a stapled Feature is configured to be automatically activated and the FeatureActivated method of the Feature's feature receiver needs to modify the Home page (default.aspx) of the site the feature is being activated on. Features that have been stapled to a site definition are processed like any other Feature, before elements from the site definition are provisioned. Because of the ordering of events, the default.aspx page will not yet exist when the FeatureActivated method is called. The solution to the problem in this situation is to provision the required page as part of the feature by using a File element within the Feature's element manifest. For more information about provisioning files with a feature, see How to: Provision a File. The sample files shown in the next section also illustrate how to provision the default.aspx page with a stapled Feature.
Sample Code
This section shows the Feature.xml and Elements.xml files that can be used to create a Feature that is stapled to all site definitions. The first XML shown is from the feature's Feature.xml file. The sample Feature has a Feature event receiver associated with it and is scoped to be activated at the Web level.
<Feature
Id="33D190F9-9A3C-40a8-B76E-16B7C714EEA5"
Title="Sample Feature: Check for Home Page"
Description="This feature uses a feature event receiver to check for the existence of the Home page."
Scope="Web"
Hidden="FALSE"
ReceiverAssembly="FeatureStapleSample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d3a14a1c1f842511"
ReceiverClass=" FeatureStapleSample.FeatureReceiver"
xmlns="https://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="elements.xml" />
</ElementManifests>
</Feature>
The Feature's Elements.xml file uses the File element to provision the default.aspx page with the Feature. This makes the page available when the Feature's event receiver runs at activation time.
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<Module Name="HomePage">
<File Url="default.aspx" Type="Ghostable" />
</Module>
</Elements>
The following code sample shows the feature receiver's FeatureActivated method attempting to access the default.aspx page of the site. If the Feature is stapled and is configured to be automatically activated, the default.aspx page will not be available unless the page with the Feature has been provisioned.
public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
SPWeb web = (SPWeb)properties.Feature.Parent;
SPFile spFile = web.GetFile("default.aspx");
if (spFile.Exists)
{
// Do something with the page
}
}
The following XML is from the Feature.xml file for the Feature that staples the preceding Feature to all site definitions.
<Feature
Id="72B1C4B2-0860-442d-9A05-DC6054045A32"
Title="Sample Feature: Illustrate Feature Stapling"
Description="This feature illustrates feature stapling."
Scope="WebApplication"
Hidden="FALSE"
xmlns="https://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="elements.xml" />
</ElementManifests>
</Feature>
The stapling feature's Elements.xml file associates the first feature with all site definitions by using the FeatureSiteTemplateAssociation element to specify the feature's ID and the GLOBAL site definition name.
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<FeatureSiteTemplateAssociation
Id="33D190F9-9A3C-40a8-B76E-16B7C714EEA5"
TemplateName="GLOBAL" />
<FeatureSiteTemplateAssociation
Id="33D190F9-9A3C-40a8-B76E-16B7C714EEA5"
TemplateName="STS#1" />
</Elements>
Automatically Activating Stapled Features
Many times you may want a stapled Feature to automatically activate when the site is created. In order for this to occur, the stapling Feature that specifies the associations between Features and site definitions must be activated. You can activate the stapling Feature by using the SharePoint Central Administration site, or from the command line and by using the Stsadm.exe tool. Figure 1 shows Feature activating by means of the SharePoint Central Administration site.
Figure 1. Activating the stapling feature
.jpg "Manage Web Application Features")
Conclusion
The Feature stapling technique allows you to attach—or "staple"—a SharePoint Feature to a site definition without making any changes to the original site definition. This gives you greater flexibility to add your Features and to safely customize all sites that are created by using that site definition. When you combine Feature stapling with Feature event receivers, your custom code Feature is executed every time a site is being created.
Additional Resources
For more information, see the following resources: