Summary
This third post is about creating and using Features in a general sense. Creating Features for each specific element will be the subject of later posts. Check the first post SharePoint 2007 Deployment: Overview for an introduction and the series index.
Feature Scopes
A Feature can be activated or deactivated in a specific scope, and there are four different scopes:
- Farm – The elements will be deployed at the farm level. To activate or deactivate a farm-scoped Feature, go to Central Administration, Operations section, and click on Manage Farm Features in the Global Configuration group.
- Web Application – The elements will be deployed at the web application level. To activate or deactivate a web application-scoped Feature, go to Central Administration, Application Management section, and click on Manage Web Application Features in the SharePoint Web Application Management group.
- Site Collection – The elements will be deployed at the site collection level. To activate or deactivate a site collection-scoped Feature, go to the root web site settings, and click on Site Collection Features in the Site Collection Administration group. You must be a site collection administrator to see this setting.
- Web Site – The elements will be deployed at the web site level. To activate or deactivate a web site-scoped Feature, go to the web site settings, and click on Site Features in the Site Administration group. You must have ManageWeb permissions (for instance, being a site administrator) to see this setting.
Each type of element can be deployed to one or more of these scopes. When describing each element type, I will specify to which scopes they can be deployed to.
Feature Schema
To create a Feature you must create a XML file named feature.xml
which contains all the general configurations for the Feature and the references to all the files that describe the Elements contained in the Feature. Below is an example of a feature.xml
file that uses all possible attributes, just for demonstration purposes. Required attributes are printed in bold.
<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
Id="AB30188E-6F5D-4380-89D9-46F5D43E25F7"
Scope="Site"
Title="My Feature"
Description="My Feature includes several elements."
Version="1.0.0.0"
Creator="André Vala"
SolutionId="2530188E-6F5A-433B-89D9-BA98D43E25F7"
ImageUrl="/_layouts/MyFeature/MyFeatureIcon.jpg"
ImageUrlAltText="My Feature Icon"
Hidden="FALSE"
ActivateOnDefault="FALSE"
AlwaysForceInstall="FALSE"
AutoActivateInCentralAdmin="FALSE"
RequireResources="TRUE"
DefaultResourceFile="MyResourceFile"
ReceiverAssembly="MyFeatureReceiver, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=3f5df55c01ba1c99"
ReceiverClass="MyFeatureReceiver.MyReceiverClass">
<ActivationDependencies>
<ActivationDependency FeatureId="C03829C4-0E85-4DCE-90F8-B7E3F008A0C5"/>
</ActivationDependencies>
<ElementManifests>
<ElementManifest Location="MyElement1.xml"/>
<ElementManifest Location="MyElement2.xml"/>
<ElementManifest Location="MyElement3.xml"/>
<ElementFile Location="MyFile1.jpg"/>
<ElementFile Location="MyFile2.jpg"/>
</ElementManifests>
<Properties>
<Property Key="MyProperty" Value="MyValue" />
</Properties>
</Feature>
Tip: To make things easier when creating these files in Visual Studio 2005 (or later), you can use the wss.xsd
schema file, included with SharePoint (usually in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\XML
), to enable Intellisense.
Feature Element
The <Feature>
element is the root element of the feature.xml
file and it has several possible attributes, although not all of them are required:
Id
(required): Unique identifier for this feature (GUID).Scope
(required): Scope in which the Feature will be activated/deactivated. Can assume the valuesFarm
,WebApplication
,Site
andWeb
(as described in the first section of this post). Keep in mind that the elements you want to include in the feature might dictate what will be its scope.Title
(optional): Title of the Feature as shown in the Feature list.Description
(optional): Description of the Feature as shown in the Feature list, below the Feature title.Version
(optional): Version number of the Feature.Creator
(optional): Name of the author of the Feature.SolutionId
(optional): ID of the Solution that the Feature belongs to.ImageUrl
(optional): URL of the image that will be used as icon in the Feature list. If this attribute is not present, SharePoint will use the default Feature icon.ImageUrlAltText
(optional): Alternative text used in the Feature icon.Hidden
(optional): Specifies if the Feature should be hidden from the Features list. The default value isFALSE
.ActivateOnDefault
(optional): Specifies if the Feature should be automatically activated after it is installed. This attribute is only used if the Feature scope isFarm
orWebApplication
, otherwise it is ignored. The default value isTRUE
.AlwaysForceInstall
(optional): Specifies if the Feature should always be installed, even if it's already installed. The default value isFALSE
.AutoActivateInCentralAdmin
(optional): Specifies if the Feature should automatically be activated in its scope. This attribute has no meaning for Features of scopeFarm
. The default value isFALSE
.RequireResources
(optional): Specifies if SharePoint should look for a culture-specific resource file for this Feature. If there is no resource file for the current culture, the Feature is hidden in the Features list (but can still be activated by object model or console command). The default value isFALSE
.DefaultResourceFile
(optional): Defines the name of the resources files. By the default all resource files are namedResources.XX-xx.resx
(whereXX-xx
is the culture code), but setting this attribute with the valueMyResourceFile
will cause SharePoint to look for filenames likeMyResourceFile.XX-xx.resx
ReceiverAssembly
(optional): Full qualified name of the assembly that contains the Custom Feature Event Receiver class. This attribute is always used with theReceiverClass
attribute.ReceiverClass
(optional): Name of the class that implements the Custom Feature Event Receiver. This attribute is always used with theReceiverAssembly
attribute.
Activation Dependencies
The <ActivationDependencies>
element is optional and is used when you want to create a dependency between two Features. In other words, if a certain Feature A depends on some Element from a Feature B, creating an activation dependency in Feature A ensures that it won't be activated if Feature B is not activated first. This element can contain any number of <ActivationDependency>
elements whose only attribute (FeatureId
) is the ID of the Feature upon which this Feature is dependent.
Element Manifests
The <ElementManifests>
element is also optional although it is used very often since it contains the list of Elements that belong to the Feature. This element can contain two types of child elements:
- The
<ElementManifest>
element, which points to a XML file that describes one or more SharePoint Feature Elements. - The
<ElementFile>
element, which points to a generic file that is part of the Feature but is not an Element Manifest. An example of such a file can be a master page or a.webpart
file.
Both elements have a Location
attribute that must contain the path to the referenced file. Most of the next posts in this series describe each type of Element Manifest.
Properties Element
The <Properties>
element is optional and it defines a property bag that can be accessed in Custom Feature Event Receivers. This element contains <Property>
elements which have two attributes:
Key:
Name of the property key, in the property bag.Value:
Value of the property, in the property bag.
This property bag can be very useful to send parameters to a Custom Feature Event Receiver whose behavior can be parameterized.
Feature Installation and Uninstallation
Although the best way to install a Feature is through a Solution, you can do it manually. Just keep in mind that you must do it in all the servers of the farm (whereas with the Solution, the multi-server deployment is automatically assured).
To install a Feature you have to create a folder in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES
with the name of the Feature and copy the feature.xml
and any other files (like Element Manifests) to that folder. Then you have to execute the following console command:
stsadm -o installfeature -name MyFolderName
Where MyFolderName
is the name you gave the folder that contains the Feature.
To uninstall the Feature you have to execute the opposite console command (see below) and remove the folder you created.
stsadm -o uninstallfeature -name MyFolderName
Feature Activation and Deactivation
Similarly, besides activating and deactivating the Feature using the SharePoint UI, you can do it using console commands. To activate a Feature you have to execute the following command:
stsadm -o activatefeature -name MyFolderName -url http://MyServer/MyWebSite
Where MyFolderName
is the name of the folder that contains the Feature, and http://MyServer/MyWebSite
is the URL address of the web site where you want to activate the Feature.
To deactivate it, you call the opposite command, as shown below:
stsadm -o deactivatefeature -name MyFolderName -url http://MyServer/MyWebSite