Deploying Features

Once you've created your custom Feature and copied the Feature into the Features directory on your Web front-end server, you need to install that Feature before you can use it on your SharePoint sites. Installing a Feature is a two-step process. It includes both installing the Feature on the Web front-end server and activating the Feature to a given scope. However, developing and working with Features also necessitates removal or reinstallation of Features, or both, invoking the need to deactivate and uninstall Features.

This section looks at the methods for installing, activating, deactivating, and uninstalling Features, specifically by using the stsadm.exe command-line tool and the administrative user interface. Information about manipulating Feature deployment using the SharePoint object model can be found in the Windows SharePoint Services 3.0 SDK. Information on deploying Features via SharePoint site definitions is included in the "Including Features in Site Definitions" section of this chapter. Table 26-5 summarizes the methods for managing the Feature life cycle.

Table 26-5: Methods for Managing Feature Deployment and Life Cycle
Open table as spreadsheet

Function	Methods
Install Feature	Stsadm.exe command-line tool SharePoint Object Model
Activate Feature	Stsadm.exe command-line tool Administrative User Interface SharePoint Object Model SharePoint Site Definition
Deactivate Feature	Stsadm.exe command-line tool Administrative User Interface SharePoint Object Model
Uninstall Feature	Stsadm.exe command-line tool SharePoint Object Model

Using Stsadm.exe and Feature Commands

Features can be installed and managed using the stsadm.exe command-line tool, which is located at the following path:

• %SystemDrive%\Program Files\Common Files\Microsoft Shared\Web server extensions\12\BIN

For example, back in the "Installing and Activating a Feature" section, you installed the LinkingExample Feature by typing the stsadm.exe -o installfeature -name LinkingExample command at your Windows command prompt. Figure 26-16 shows the resultant output in the command window, which includes the parameters for installing a Feature using the command-line tool. In this case, the optional -force parameter is included in the command line because the Feature is being installed for a second time. The -force parameter is used where you have updated a Feature and then need to redeploy that Feature to push updates to existing instances of that Feature already activated throughout sites.

Figure 26-16: Stsadm.exe command to reinstall the LinkingExample Feature

More Info 

See the "Create System Path to stsadm.exe Command-Line Tool" sidebar to create a shortcut for accessing the stsadm.exe tool.

Table 26-6 summarizes the Feature commands available using the stsadm.exe command-line tool. The syntax for each command will be demonstrated in the upcoming sections. You can obtain the syntax for each command by using the stsadm.exe help command. For instance, to discover the syntax for the Activatefeature command, type in stsadm.exe -help activatefeature at your Windows command prompt then press the return key on your keyboard.

Table 26-6: Feature Stsadm.exe Commands
Open table as spreadsheet

Command	Description
Installfeature	Installs the Feature to the specified scope, such as Farm or Web.
Activatefeature	Activates the Feature for the specified scope, or to a specific Web using the -url parameter.
Deactivatefeature	Deactivates a Feature from the existing scope.
Uninstallfeature	Completely removes the Feature from the specified scope.
Scanforfeatures	Displays a list of Features currently installed on the server.

The scanforfeatures command returns a list of installed Features on the Web front-end server, regardless of scope. For example, typing the stadam.exe -o scanforfeatures command returns a complete list of installed Features for the farm. This command also returns any failed Feature installations, including the name of the failed Feature, such as in the following command output:

 Failed feature installations <Check the logs for more details>: The Feature at 'folder\feature.xml' is corrupt. Please re-install the Feature. 

You can also save the scanforfeatures output to a text file, such as by specifying a text file to which to save the results to. For example, type the stsadm.exe -o scanforfeatures > filename.txt command to do this.

Real World Create System Path to Stsadm.exe Command-Line Tool

You can access the stsadm.exe command from any command prompt location on your server. You can also include a direct path to your stsadm.exe command by creating a system path. To do this, complete the following steps:

1. Click Start and then click Control Panel.

2. In the Control Panel window, double-click System.

3. In the System Properties dialog box, click the Advanced tab.

4. On the Advanced tab, click the Environmental Variables button.

5. In the System Variables section of the Environmental Variables window, browse to the Path Variable and click Edit.

6. In the Variable value box, scroll to the last entry, add a semi colon (;), and then add the path to the stsadm.exe command-line tool as follows:

   • %SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN

7. Click OK to save the new path, and then click OK on the Environmental Variables dialog box to save your changes. Click OK on the System Properties tab to exit.

You can now enter the stsadm.exe command prompt location on your server.

Permissions for Deploying Features

A server administrator is responsible for installing and uninstalling Features on the Web front-end server, using the stsadm.exe command-line tool. After Features are installed, they can be activated or deactivated at the given scope. Table 26-7 summarizes the required permissions for activating and deactivating Features through the administrative user interface.

Table 26-7: Permissions to Activate and Deactivate Features
Open table as spreadsheet

Feature scope	Permission/role
Farm	Farm Administrator
Web Application	Farm Administrator
Site Collection	Site Collection Administrator
Web	Site Collection Administrator

Adding Feature Files to a Web Server File Location

After you've created your Feature and before you install it, you need to copy the folder containing your Feature to the Features directory on your Web front-end server, which can be found at the following location:

• %SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES

Ensure that you include any files and subfolders belonging to a Feature as part of that parent folder, such as any pages or elements files being provisioned as part of the Feature. When you install the Feature using the -name parameter in the stsadm.exe command-line tool, SharePoint looks for the Feature in the Features directory by default.

Important 

There's a common scenario you might want to avoid. If, when using Windows Explorer,you create a new folder in the Features directory the new folder may not have inherited permissions. If you subsequently deploy a Feature in that new folder and permissions haven't correctly propagated, some SharePoint pages, such as site settings or list view pages, will throw an exception. To fix this problem, right-click the new folder, click Properties, click Security, and then click Advanced. On the Permissions tab, select the option "Allow Inheritable Permissions from the parent to propagate to this object and all child objects. Include these with entries explicitly defined here". Click OK. Alternatively, you can avoid this problem by creating the new folder at the command prompt by using the md command.

Installing Features

Before you can activate a Feature, you must install the Feature. To install the Feature using the stsadm.exe command-line tool, complete the following steps:

1. Launch the Windows command line, and browse to the location of the stsadm.exe command-line tool (if you haven't already created a system path for it).

2. Type the following command:

    stsadm.exe -o installfeature -name LinkingExample 

   OR

    stsadm.exe -o installfeature -filename featurefolder\feature.xml 

   If you are re-installing a Feature-for example, to include some changes or additional functionality-you need to include the -force parameter at the end of the command like this:

    stsadm.exe -o installfeature -name LinkingExample -force 

Be sure to do an IISRESET after running this command.

For more information about re-installing and updating Features, see the "Updating an Existing Feature" section in this chapter.

Activating Features

In addition to installing a Feature, you must activate a Feature before it can be used in the target scope, such as Web or Site. By default, Features are set to a status of deactivated following installation. The one exception occurs when a Feature is deployed as part of a site definition, where it will be activated when a site is provisioned based on the site definition containing the Feature.

To activate Features using the stsadm.exe command-line tool, complete the following steps:

1. Launch the Windows command line, and browse to the location of the stsadm.exe command line tool (if you haven't already created a system path for it).

2. Type the following command:

    stsadm.exe -o activatefeature -name LinkingExample -url targetsite 

   Note 

   Farm-scoped Features are activated by default when installed.

To activate a Web-scoped Feature through the administrative user interface, complete the following steps:

1. Browse to the Web (or site) where you want to activate the Feature, and browse to the Site Settings page-for example, http://server/sites/site/_layouts/settings.aspx.

2. Under the Site Administration section on the Site Settings page, click the Site Features link.

3. On the Site Features page, locate the Feature you want to activate and click the Activate button in the Status column to activate the Feature.

For example, in Figure 26-17 the LinkingExample Feature has been activated on the Fabrikam site, denoted by the Name of Toolbar And Menu Links and the display of the Active Status button alongside the Feature.

Figure 26-17: Feature activation through the administrative user interface

Features can also be activated through site definitions. This method is explained in the "Including Features in Site Definitions" section of this chapter.

Using Activation Dependencies and Scopes

Features can include activation dependencies on other Features, such as a Feature B being activated when Feature A is activated. Feature activation dependencies provide a means to streamline Feature activation throughout your SharePoint sites. Activation dependencies are included in the  Feature.xml file by the <ActivationDependencies> attribute, such as:

 <ActivationDependencies>  <ActivationDependency Feature /> <!-- name of Feature --> </ActivationDependencies> 

A Default Feature Activation Dependency

One example of a default Feature activation dependency is the Announcements List Feature, which is activated when the Team Collaboration Feature is activated. Open the Team Collaboration Feature  Feature.xml file, which can be found at the following location:

• %SystemDrive%\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\TeamCollab

You should be able to see that there are a number of Features dependent on activation of the Team Collaboration Feature. The Team Collaboration Feature itself is automatically activated when new sites are provisioned from the STS site definition, such as the Team Site, where it is included as part of that site definition. If you deactivated the Team Collaboration Feature, you would also deactivate the dependent Features. See the "Including Features in Site Definitions" section to learn about enabling Feature activation through site definitions.

Hidden features are Features that have the Hidden attribute set to True in the Features.xml file. A dependent Feature, or a Feature depending on another Feature for activation, can be either hidden or visible if it is in the same scope as that Feature. However, a Feature, such as the Team Collaboration Feature, sponsoring other Feature activations cannot be hidden.

You can have cross-scope Feature activation dependencies, such as a Web-scoped Feature that is dependent on a site collection-scoped Feature. However, there are some general rules regarding cross-scope Feature activations. For example, when a Web-scoped Feature is dependent on activation of a site collection-scoped Feature, the Web-scoped Feature cannot be hidden. For details concerning Feature activation dependency cross-scope rules, see the Windows SharePoint Services 3.0 Software Development Kit.

Deploying Features by Using Solutions

In SharePoint Server 2007, Solutions are used to package and deploy Features, site definitions, Web Parts, template files, assemblies, and Code Access Security (CAS) policies to SharePoint Web front-end servers. Solutions supersede the wppackage deployment tool used in Windows SharePoint Services 2.0, and they eliminate manual deployment methods, such as the need to manually copy files and modify the Web.config files on Web front-end servers.

On the CD 

The sample Solution files used in this section are included on the book's CD in the \Code\Chapter 26 folder. This includes the  Manifest.xml file,  SharePointFeatures.DDF file, and Package folder, which includes the  SharePointAC.wsp file.

Steps for Creating a Solution Package

The steps for creating a Solution package for deploying Features are as follows:

1. Create  Manifest.xml file as part of the Visual Studio project containing the Features and associated files to be included in the Solution package.

2. Create the .ddf file as part of that same project. (The .ddf file contains information to compress files into a CAB file.)

3. Download and extract the Microsoft Cabinet Software Development Kit from http://support.microsoft.com/kb/310618/en-us.

4. In the Windows command line, run Makecab.exe on the .ddf file to generate a .wsp file. Include the path to the Makecab.exe file, or copy the Makecab.exe file into the same directory containing the Visual Studio project files, which includes the  Manifest.xml and .ddf file.

5. Use the stsadm.exe command-line tool to add your .wsp file into the SharePoint Solution store.

6. Deploy the Solution package by using the stsadm.exe command-line tool, the SharePoint Solution Management administrative page, or the object model.

Creating the Manifest.xml File

To create the  Manifest.xml file, complete the following steps:

1. Add a new file to the project containing your Features, and name the file  Manifest.xml.

2. In the  Manifest.xml file, include a reference to the SharePoint schema. This activates the IntelliSense feature and enables access to the Solution schema.

3. Populate the  Manifest.xml file to include the Features you want to deploy as part of the Solution package. In the following example, two Features from the SharePoint project have been included as well as the project assembly reference, which is required for the event handler that is part of the SiteColumnHandler Feature:

    <?xml version="1.0" encoding="utf-8" ?> <Solution Solution   xmlns=http://schemas.microsoft.com/sharepoint/>   <FeatureManifests>     <FeatureManifest Location="LinkingExample\Feature.xml"/>     <FeatureManifest Location="SiteColumnHandler\Feature.xml"/>   </FeatureManifests>   <Assemblies>     <Assembly DeploymentTarget="GlobalAssemblyCache"           Location="SharePoint.dll">       <SafeControls>         <SafeControl           Assembly="SharePoint, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ad7f6a147689147c"           Namespace="SharePoint"           TypeName="*" Safe="True" />       </SafeControls>     </Assembly>   </Assemblies> </Solution> 

   Note 

   You need to generate a GUID for your Solution Manifest file. Use the Guidgen.exe tool to do this. Unlike what you did for the GUID in the  Feature.xml file, this time leave the surrounding braces intact.

Creating the Diamond Directive File (.ddf)

To create the Diamond Directive file, add a new file to the same project containing the  Manifest.xml file and give it the .ddf extension-for example,  SharePointFeatures.ddf. The following example .ddf file includes references to the  Manifest.xml file, as well as the assembly and Features to be included as part of the CAB, and it provides Makecab.exe with the directives to compress the files into the CAB:

 ;*** SharePoint Features Example MakeCAB Directive file ; .OPTION EXPLICIT ; Generate errors .Set CabinetNameTemplate=SharePointAC.wsp .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory .Set CompressionType=MSZIP ;** All files are compressed in cabinet files .Set UniqueFiles="OFF" .Set Cabinet=on .Set DiskDirectory1=Package ; ; ** CAB Root manifest.xml SharePoint.dll ; ; ** LinkingExample Feature .Set DestinationDir=LinkingExample Features\LinkingExample\Feature.xml Features\LinkingExample\Menu.xml Features\LinkingExample\Toolbar.xml Features\LinkingExample\Help.aspx ; ** SiteColumnHandler Feature .Set DestinationDir=SiteColumnHandler Features\SiteColumnHandler\Feature.xml Features\SiteColumnHandler\Elements.xml ;*** End 

Generate the CAB and WSP File

Open your Windows command-line tool, browse to the location of the project containing the  Manifest.xml and .ddf files, and type the following command:

 Makecab.exe -f sharepointfeatures.ddf 

Upon successful execution, Makecab.exe generates a new folder, named Package. The Package folder contains a .wsp file, which is the file you will use to add the Solution to your SharePoint Solution store. The name of the .wsp file will be that name defined in the .ddf file's CabinetNameTemplate declarative, in this case  SharePointAC.wsp.

Deploying the Solution

To deploy the Solution, you need to add the Solution to the SharePoint Solution store. To do this, complete the following steps:

1. Launch the Windows command-line tool, browse to the location containing the .wsp file, and type the following command:

    stsadm.exe -o addsolution -filename sharepointac.wsp 

2. Browse to SharePoint Central Administration, and click the Operations tab. On the Operations page under the Global Configuration section, locate and click the Solution Management link.

3. On the Solution Management page, shown in Figure 26-18, click the  Sharepointac.wsp Solution link.

4. On the resultant Solution Properties page, click the Deploy Solution link in the toolbar.

5. On the Deploy Solution page, shown in Figure 26-19, configure the deploying options, including scheduling the Solution and choosing to deploy the Solution to all Web Applications or a specific Web Application.

   Note 

   The warning about the deployment of the Solution to the GAC appears on the Deploy Solution page because the value of the assembly DeploymentTarget attribute in the  Manifest.xml file is set to "GlobalAssemblyCache".

Figure 26-18: Added Solution shown on the Solution Management page

Figure 26-19: Deployment options for the Solution

Deactivating and Uninstalling Features

You can choose to deactivate instances of Feature. For example, you can turn off a particular functionality on your sites or a given site, or you can choose to uninstall a Feature, which completely removes the Feature from your SharePoint deployment. Features can be deactivated either through the administrative user interface or by using the stsadm.exe command-line tool.

To deactivate the Feature from a site using the administrative user interface, complete the following steps:

1. Browse to the site where you want to deactivate the Feature, click Site Actions, and under Site Administration, click Site Features.

2. On the Site Features page, locate the Feature you want to deactivate and click the Deactivate button to deactivate the Feature.

When you deactivate a Feature using the administrative user interface, you receive a warning message, as shown in Figure 26-20.

Figure 26-20: Warning message when deactivating Features through the administrative user interface

To deactivate the Feature using the stsadm.exe command-line tool, open the Windows command-line tool and type the following command:

 stsadm.exe -o deactivatefeature -name LinkingExample -url 

The URL parameter defines the URL of the site where you want to deactivate the Feature. Failure to enter the URL parameter results in a message notifying you the Feature was not deactivated, as shown in Figure 26-21.

Figure 26-21: Attempting to deactivate Features without the required URL parameter

To uninstall the Feature using the stsadm.exe command-line tool, open the Windows command line tool and type the following command:

 stsadm.exe -o uninstallfeature -name LinkingExample 

Important 

The stsadm.exe uninstallfeature command does not remove the Feature folder from the Features directory.

You should deactivate Features before uninstalling them, unless they are Web-scoped or farm-scoped Features. If you attempt to uninstall a site or Web-scoped Feature before deactivating that Feature, you receive a message notifying you that the Feature is still activated but you can optionally use the -force parameter to forcibly remove the Feature without deactivating it, as shown in Figure 26-22.

Figure 26-22: Attempting to uninstall an active Feature

Files deployed as part of the Feature <Module> element, such as an ASPX page, are not removed when a Feature is uninstalled. For example, if you deploy an ASPX page as part of a Feature and you then uninstall the Feature, you can still navigate to that ASPX page by typing the path to that page into the address line of your browser.

Updating an Existing Feature

You might find it necessary to update a Feature after installation. For example, you might want to modify a toolbar link or add a resource file, or you might add and deploy an event handler to existing instances of a Feature. To update an existing Feature, you must reinstall the Feature using the -force parameter and perform an IISRESET. You can do this by typing the following stsadm.exe command:

 stsadm.exe -o uninstallfeature -name LinkingExample -force 

Alternatively, you can include the AlwaysForceInstall attribute in the  Feature.xml file and set the value to True, such as AlwaysForceInstall="TPYE". This removes the need to enter the -force parameter in the command line during uninstall.

You should avoid changing the scope on an existing Feature in scenarios where that Feature has been activated within the given scope. For example, if you change the scope on an existing Feature from Web to Site, you need to reinstall the Feature, perform an IISRESET, and then attempt to deactivate the Feature from sites where the Web-scoped Feature was previously deployed and activated. Through the administrative user interface, you'll receive a warning message stating, "The Feature Is Not Currently Active," and you will not be able to deactivate the Feature from the previous scope.

Attempting to deactivate the same Feature through the stsadm.exe command-line tool also generates an error, as shown in Figure 26-23.

Figure 26-23: Attempting to deactivate a Feature after a scope change

To deactivate Features from the previous scope, change the Feature back to the original scope, deactivate instances of the Feature from the original scope, uninstall the Feature, and then reinstall the Feature to the new scope.