SharePoint 2007 Deployment: Creating and Using Features

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 values Farm, WebApplication, Site and Web (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 is FALSE.
• ActivateOnDefault (optional): Specifies if the Feature should be automatically activated after it is installed. This attribute is only used if the Feature scope is Farm or WebApplication, otherwise it is ignored. The default value is TRUE.
• AlwaysForceInstall (optional): Specifies if the Feature should always be installed, even if it's already installed. The default value is FALSE.
• AutoActivateInCentralAdmin (optional): Specifies if the Feature should automatically be activated in its scope. This attribute has no meaning for Features of scope Farm. The default value is FALSE.
• 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 is FALSE.
• DefaultResourceFile (optional): Defines the name of the resources files. By the default all resource files are named Resources.XX-xx.resx (where XX-xx is the culture code), but setting this attribute with the value MyResourceFile will cause SharePoint to look for filenames like MyResourceFile.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 the ReceiverClass attribute.
• ReceiverClass (optional): Name of the class that implements the Custom Feature Event Receiver. This attribute is always used with the ReceiverAssembly 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