Deploying developed site element customizations

Applies To: Office SharePoint Server 2007

This Office product will reach end of support on October 10, 2017. To stay supported, you will need to upgrade. For more information, see , Resources to help you upgrade your Office 2007 servers and clients.

Topic Last Modified: 2016-11-14

In this article:

• Deploying developed site elements by using solution packages

• Deploying developed site elements by using Features

This article provides guidance on the deployment of developed site element customizations by using Microsoft Office SharePoint Server 2007, including deployment procedures, general considerations, and best practices related to deploying custom code.

Developed site elements are applications and files that provide functionality to a site — for example, a workflow that implements a business process, or a site template that enables users to create sites of a particular design. Developed site elements are deployed on the farm's Web servers or, in some cases, on dedicated application servers in the middle tier of the farm.

The sections in this article describe how to work with the different methods of deploying developed site elements in Office SharePoint Server 2007, including procedures that describe how to import, export, and create solution packages and Features.

This article does not discuss deployment of authored site elements, such as Web pages, cascading style sheets, and layout pages. For information about deployment of authored site elements, see Deploying authored site element customizations. For more information about the differences between authored site elements and developed site elements, see Review of site elements.

Before reading this article, you should familiarize yourself with the concepts related to designing and building sites. For more information, see About designing and building sites.

The procedures in this article are based on the topologies described in the article Customization scenarios, and may not exactly conform to your environment.

These procedures may require a cooperative effort between several different roles. Additionally, this article assumes that scheduled deployment jobs will be used to migrate content between certain layers of the topology.

The following table summarizes the deployment methods described in this article.

The following sections describe each listed deployment method in detail.

Deploying developed site elements by using solution packages

In this section:

• What is a solution package?

• When to use solution packages

• Deploy a solution by using Central Administration

• Create a solution package

• Import a solution package by using the Stsadm command-line tool

• Deploy a solution package by using the Stsadm command-line tool

What is a solution package?

A solution package is a distribution package that delivers your custom Office SharePoint Server 2007 and Windows SharePoint Services 3.0 development work to the Web servers or the application servers in your server farm. A solution package is a CAB file with a .wsp file name extension and a manifest file. Solution packages can be created manually by using tools such as Makecab.exe, or they can be created with the Solution Generator, a stand-alone application included in the Windows SharePoint Services 3.0 Tools: Visual Studio 2005 Extensions (https://go.microsoft.com/fwlink/?LinkID=107267&clcid=0x409).

Components that can be packaged in a solution include:

• .NET Framework assemblies that wrap the code that drives the solution.

• Deployment files such as resource files, images, or other helper files.

• New templates and definitions for sites, lists, libraries, fields, content types, and more. These definitions are in the form of CAML-based XML files.

• Features, which allow you to activate and deactivate code in a Web site.

• Configurations that must be performed at the Web-server level — for example, the Web.config files for the registration of Web Parts.

For more information, see Solution package components.

When to use solution packages

You can use solution packages to deliver developed site elements and artifacts (which are described in Deploying authored site element customizations). You can also use solution packages are to deploy developed site elements in disconnected environments, or to save developed site elements to a software configuration management system.

You can use solution packages to deploy developed site elements if one or more of the following factors apply:

• **Disconnected environments  ** If the farms are disconnected, you should create a solution package for asynchronous transfer to the integration farm.

• Software configuration management environments   You can consolidate development work in a solution package for delivery to a software configuration management system.

• Include Features and other developed site elements   You can include Features with other customizations in a solution package. If some of your customizations are packaged as Features and others are not, you can use solution packages as your standard deployment medium.

• Tandem delivery of artifacts and developed site elements   You can use a solution package if you want to deploy both artifacts and developed site elements in a single deployment package.

• Scripted deployments   You can use solution packages if you want to write a script to automate the deployment process of developed site elements.

As shown in the deployment diagrams in the article Customization scenarios, you can use solution packages to deploy developed site element customizations between developer workstations and an integration farm or a software configuration management system, and between an integration farm and authoring client workstations and pilot or production farms.

Deploy a solution by using Central Administration

You can deploy imported solutions from the Central Administration site. When a solution has been imported to the solution database by using the Stsadm -Addsolution operation as described in the section Import a solution package by using the Stsadm command-line tool later in this article, it must be deployed to a site before it can be accessed.

The following procedure shows how to deploy an imported solution to a site in the farm.

Deploy a solution in the Central Administration site

1. On the top link bar of the Central Administration site, click Operations.

2. On the Operations page, in the Global Configuration section, click Solution management.

3. On the Solution Management page, click the solution that you want to deploy.

4. On the Solution Properties page, click Deploy Solution.

5. On the Deploy Solution page, in the Deploy When section, select one of the following:

   • Now

   • At a specified time. If you select this option, specify a time by using the date and time boxes. It is recommended that you select a time when the load on the destination servers is low.

6. In the Deploy To? section, in the A specific web application list, click either All web applications or select a specific Web application.

7. Click OK.

Create a solution package

This section describes methods of creating solution packages containing developed site elements and artifacts. There are several different methods of creating a solution package. The following table summarizes the methods that are described in this section.

Manually create a solution package

Developers of Office SharePoint Server 2007 solutions will often manually create SharePoint solution packages when there is a need to do any of the following:

• Deploy .NET Framework assemblies in the private application folder instead of the global assembly cache.

• Add code access security permissions to the solution that must be applied during the deployment.

• Deviate from the names used by default for the Feature folders.

• Localize the solution.

• Associate Feature event handlers to certain types of Windows SharePoint Services 3.0 solutions, such as Web Part solutions.

• Add resources (XML files, pictures, .dll files, and assemblies) to the solution package.

To manually create a solution file, you perform the following basic steps:

1. Collect all individual solution files in a folder. There are no concrete guidelines about how you should do this, but a best practice is to separate the different types of solution files into their own subfolders.

2. Create a manifest.xml file that lists the components of the solution.

3. Create a .ddf file that defines the structure of the Windows SharePoint Services 3.0 solution file. This file contains the list of individual solution files that determine the output .wsp file.

4. Execute Makecab.exe with the .ddf file as input and the .wsp file as output.

The preceding basic steps are described in detail in the following procedure.

Manually create a solution package by using Makecab.exe

1. Create a solution manifest.xml file.

   The solution manifest (always called manifest.xml) is stored at the root of a solution file. This file defines the list of features, site definitions, resource files, Web Part files, and assemblies to process. It does not define the file structure — if files are included in a solution but not listed in the manifest.xml file, they are not processed in any way.

   Following is an example of the structure of a manifest.xml file, shown in XML.

   <?xml version="1.0" encoding="utf-8" ?>

   <Solution xmlns="https://schemas.microsoft.com/sharepoint/"

   SolutionId="{79d1a62e-3627-11db-963e-00e08161165f}"

   ResetWebServer="TRUE">

       <Assemblies>

           <Assembly DeploymentTarget="GlobalAssemblyCache"

   Location="Example.Sharepoint.Webparts\

   Example.SharePoint.WebParts.dll">

               <SafeControls>

                   <SafeControl Assembly="Example.Sharepoint.Webparts,

   Version=1.0.0.0, Culture=Neutral, PublicKeyToken=63cce650e8605f5d"

   Namespace="Example.Sharepoint.Webparts" TypeName="*"/>

               </SafeControls>

           </Assembly>

           <Assembly DeploymentTarget="GlobalAssemblyCache"

   Location="Example.Sharepoint.Timer/Example.Sharepoint.Timer.dll"/>

       </Assemblies>

       <FeatureManifests>

           <FeatureManifest Location="Example.Sharepoint.Timer\Feature.xml"/>

           <FeatureManifest Location="Example.CustomType\Feature.xml"/>

           <FeatureManifest Location="Example.ExampleLibrary\Feature.xml"/>

           <FeatureManifest Location="Example.Columns\Feature.xml"/>

           <FeatureManifest Location="Example.Workflow.ProcessExample\Feature.xml"/>

           <FeatureManifest Location="Example.Workflow.ProvisionExample\Feature.xml"/>

       </FeatureManifests>

       <SiteDefinitionManifests>

           <SiteDefinitionManifest Location="EXAMPLE">

               <WebTempFile Location="1033\XML\WEBTEMPExample.XML"/>

           </SiteDefinitionManifest>

       </SiteDefinitionManifests>

   </Solution>

   In addition, you can add a DwpFiles element to specify .webpart or .dwp files, or a ResourceFiles element to specify resource files, site definitions, application resources, and code access security policies.

2. Optionally, annotate your Feature.xml files with <ElementFile> tags.

   In the <ElementManifests> tag in your Feature.xml file, add <ElementFile Location="..."/> for all the extra files in your feature, such as Active Server Page Extension (ASPX) pages (for example, allitems.aspx) or master pages, and so on.

   Note

   This step is required only if your solution contains Features.

3. Create your solution package (.wsp file).

   Because the solution file is essentially a CAB file, use the Makecab.exe tool to create the solution package. The Makecab.exe tool takes a pointer to a .ddf file, which describes the structure of the CAB file. The format of a .ddf file is similar to that of an .inf file — that is, you declare a standard header and then enumerate, one file per line, the set of files by where they are located on disk, separated by where they should be located in the CAB file. For example:

   ; .OPTION EXPLICIT    

   ; Generate errors

   .Set CabinetNameTemplate=MySolutionFile.wsp

        .set DiskDirectoryTemplate=CDROM

   ; All cabinets go in a single directory

   .Set CompressionType=MSZIP

   ;** All files are compressed in cabinet files

   .Set UniqueFiles="ON"

   .Set Cabinet=on

   .Set DiskDirectory1=Package build\manifest.xml manifest.xml build\

   MySolutionFile\Feature.xml MySolutionFile\Feature.xml ...

Walkthrough: Generating and deploying a custom Web Part solution package

This section provides an example of how to build and deploy a solution package that contains a custom Web Part. This walkthrough requires the use of Visual Studio 2005 and the Makecab.exe tool.

Office SharePoint Server 2007 offers developers the option to execute custom code when a Feature is installed, activated, deactivated, or uninstalled. An example is a Web Part that is dependent on a specific task list. When the Web Part Feature is activated, custom code can check whether this task list is part of the lists within the site. If not, the code creates the list, and then removes the list when the Feature is deactivated. The custom code is wrapped into a .NET Framework assembly referred to as the Feature Receiver Assembly.

This walkthrough assumes you have a Web Part project created. When the Web Part Feature is installed, activated, deactivated, or uninstalled, Office SharePoint Server raises asynchronous events. You can handle these events in a custom .NET Framework assembly by creating a .NET Framework class that inherits from the abstract Microsoft.SharePoint.SPFeatureReceiver class.

Walkthrough: Generating and deploying a custom Web Part solution package

1. Create the following .NET class in C#:

   using System;
   using System.Diagnostics;
   using System.Collections.Generic;
   using System.Text;
   using Microsoft.SharePoint;
   
   namespace MSDN.Samples
   {
       public class MSDNTaskListEventHandler: SPFeatureReceiver
       {
           public override void 
   FeatureActivated(SPFeatureReceiverProperties properties)
           {
               SPSite sitecollection = 
   (SPSite)properties.Feature.Parent;
               SPWeb web = sitecollection.RootWeb;
               try
               {
                   // -- Check if list exists.
                   SPList list = web.Lists["MSDN Tasks"]; 
               }
               catch 
               {
                   // -- If not, create the list.
                   web.Lists.Add("MSDN Tasks", "A custom list", SPListTemplateType.Tasks);
               }
           }
   
           public override void 
   FeatureDeactivating(SPFeatureReceiverProperties properties)
           {
               SPSite sitecollection = (SPSite)properties.Feature.Parent;
               SPWeb web = sitecollection.RootWeb;
               try
               {
                   // -- Check if list is there, and if so, delete it.
                   SPList list = web.Lists["MSDN Tasks"];
                   web.Lists.Delete(list.ID);
               }
               catch (Exception ex)
               {
               }
           }
   
           public override void 
   FeatureInstalled(SPFeatureReceiverProperties properties)
           {
           }
   
           public override void 
   FeatureUninstalling(SPFeatureReceiverProperties properties)
           {
           }
       }
   }
   

   The coding work results in two assemblies. One assembly contains the code delivering the Web Part. A second assembly contains the previous code. At the time of publication of this article, Visual Studio Extensions for Windows SharePoint Services 3.0 does not allow you to connect the event handler with the Web Part Feature definition file. In addition, Web Part assembly must be deployed in the private application folder instead of the global assembly cache. Because of this, you must manually create the solution package.

   Note

   In the following steps, the way you organize the different files representing the solution components can be adapted to your own preferences and can be part of the Visual Studio 2005 solution.

2. Create a folder with two subfolders to collect all of the solution components. A first subfolder stores the assemblies (named "Assemblies" in this article), and the second subfolder stores the different XML files defining the Features (named "Features" in this article). Copy the Web Part assembly and the event handler assembly into the Assemblies folder.

3. Create a subfolder under the Features folder for every Feature that must be included in the SharePoint solution. There is only one Feature for this walkthrough. Assume that it is called MSDNTaskCreator; the Features folder contains a subfolder with that name. At the root of this folder, add a Feature.xml file that contains the following XML.

   <Feature  Title="MSDNTaskCreator" 
             Id="55312295-a323-4333-b875-1bbe8ef7fd04" 
             Description="Small Web Part creating a custom task item" 
             Version="1.0.0.0" Scope="Site" Hidden="FALSE" 
             ReceiverAssembly="MSDNFeatureEventhandlers, 
   Version=1.0.0.0, Culture=neutral, PublicKeyToken=5e5a470a5445a8f1" 
             ReceiverClass="MSDN.Samples.MSDNTaskListEventHandler"
             DefaultResourceFile="core" 
   xmlns="https://schemas.microsoft.com/sharepoint/">
     <ElementManifests>
       <ElementManifest Location="elementManifest.xml" />
       <ElementFile Location="MSDNTaskCreator.webpart" />
     </ElementManifests>
   </Feature>
   

   This XML deviates from the XML that is generated with Visual Studio Extensions for Windows SharePoint Services 3.0 in that two additional attributes are added to the Feature.xml file:

   • The ReceiverAssembly attribute contains the full strong name of the .NET Framework assembly that contains the event handler code.

   • The ReceiverClass attribute stores the full name of the class within that assembly.

4. Create a manifest file in the root folder. It is different from the one that is generated by Visual Studio Extensions for Windows SharePoint Services 3.0. Following are the contents.

   <Solution SolutionId="d63d0395-96a4-449e-83ce-5f7239bbd3ad"

   xmlns="https://schemas.microsoft.com/sharepoint/" >

     <FeatureManifests>

       <FeatureManifest Location="MSDNTaskCreator\Feature.xml" />

     </FeatureManifests>

     <Assemblies>

       <Assembly Location="MSDNTaskCreator.dll"

   DeploymentTarget="WebApplication" >

         <SafeControls>

           <SafeControl Assembly="MSDNTaskCreator, Version=1.0.0.0,

   Culture=neutral, PublicKeyToken=9f4da00116c38ec5"

   Namespace="MSDN.Samples" TypeName="MSDNTaskCreator" Safe="True" />

         </SafeControls>

       </Assembly>

           <Assembly Location="MSDNFeatureEventHandlers.dll"

   DeploymentTarget="GlobalAssemblyCache" />

     </Assemblies>

   </Solution>

   Notice that the name of the Feature no longer includes a GUID. The first assembly element has an attribute named DeploymentTarget, with the value WebApplication instead of GlobalAssemblyCache. A second assembly element with the definition of the .NET Framework assembly contains the event handler code to deploy in the global assembly cache.

5. Now we can create the .ddf file named, in this case, .wsp_structure.ddf. Create it directly in the DeploymentFiles folder. First, add the following header information.

   ;

   ; *** .ddf file for generating SharePoint solution.

   ;

   .OPTION EXPLICIT ; Generate errors

   .Set CabinetNameTemplate=MSDNTaskCreatorWebPart.wsp

   .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single

   directory

   .Set CompressionType=MSZIP;** All files are compressed in cabinet

   files

   .Set UniqueFiles="ON"

   .Set Cabinet=on

   .Set DiskDirectory1=Package

   The header contains two parts:

   • CabinetNameTemplate is set to the name of the SharePoint solution file (MSDNTaskCreatorWebPart.wsp).

   • DiskDirectory1 is set to Package. This is the directory containing the generated .wsp file.

   The second part of the .ddf file defines the structure of the package.

   ; *** the manifest file

   manifest.xml manifest.xml

   ; *** the feature files

   Features\MSDNTaskCreator\Feature.xml MSDNTaskCreator\Feature.xml

   Features\MSDNTaskCreator\elementManifest.xml MSDNTaskCreator\elementManifest.xml

   Features\MSDNTaskCreator\MSDNTaskCreator.webpart

   MSDNTaskCreator\MSDNTaskCreator.webpart

   ; *** the assemblies

   Assemblies\MSDNTaskCreator.dll MSDNTaskCreator.dll

   Assemblies\MSDNFeatureEventhandlers.dll MSDNFeatureEventhandlers.dll

   The .ddf file is input for Makecab.exe, a tool you can get by installing the Microsoft Cabinet SDK, as described earlier in this section. You can also find Makecab.exe in the Smart Devices SDK (located by default at \Program Files\Microsoft Visual Studio 8\SmartDevices\SDK\SDKTools).

6. To facilitate the packaging and deployment, create a batch file with the following content.

   set MakeCabTool=c:\Program Files\Microsoft Visual Studio 8\

   SmartDevices\SDK\SDKTools\Makecab.exe

   set SPAdminTool=%CommonProgramFiles%\Microsoft Shared\

   web server extensions\12\BIN\stsadm.exe

   "%MakeCabTool%" /f wsp_structure.ddf

   "%SPAdminTool%" -o addsolution -filename package\

   MSDNTaskCreatorWebPart.wsp

   "%SPAdminTool%" -o deploysolution -name MSDNTaskCreatorWebPart.wsp

   -immediate -allowGACDeployment -url <URL name>

   The first two lines are the settings of the paths to the Makecab and Stsadm command-line tools. Next, there is the line creating the solution package.

   Makecab.exe /f wsp_structure.ddf
   

   As a result of the execution, MSDNTaskCreatorWebPart.wsp appears in the Package folder. The next line adds the MSDNTaskCreatorWebPart.wsp to the solution store in your server farm by executing the following command:

   stsadm.exe -o addsolution -filename 
   Package\MSDNTaskCreatorWebPart.wsp
   

   The final line in the batch file is the deployment of the solution to one of your site collections.

7. You can use the Solution management link on the Operations tab in Central Administration to deploy the solution package. Alternatively, run the following commands at the command prompt:

   cd %COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\Bin

   stsadm -o deploysolution -name MSDNTaskCreatorWebPart.wsp -local -allowGACDeployment -url <URL name>

   The Web Part Feature is now installed, but not activated.

8. To activate the Feature, open the Site Collection Features page, and then click the Activate button next to the Feature name. Because there is code that runs when the FeatureActivated event occurs, the MSDN Task list is created. Deactivating this Feature removes this task list from the root site of the site collection.

Create a solution package by using the SharePoint Solution Generator

The SharePoint Solution Generator is a stand-alone application that can convert certain types of Office SharePoint Server 2007 or Windows SharePoint Services 3.0 Web sites into a Visual Studio 2005 site definition project. Content that is not supported by the SharePoint Solution Generator includes:

• Some site and list templates, such as Wiki Site, Publishing Portal, and Collaboration Portal

• Lookup fields and custom field types

• Some site settings and list settings

For more information about the SharePoint Solution Generator, see Windows SharePoint Services 3.0 Tools: Visual Studio 2005 Extensions (https://go.microsoft.com/fwlink/?LinkID=107267&clcid=0x409).

By using the SharePoint Solution Generator user interface, you can compile a customized site into a SharePoint solution for deployment to another SharePoint farm. Some customizations may be lost when a solution is imported to a farm, including the following:

• Lookup columns disappear from any list that had them.

• Customizations to the Quick Launch for the site are lost.

• Web Parts configured on pages are lost.

• Custom List Item Event Receivers are no longer attached to the lists.

For more information, see Review of tools and processes.

Performing custom actions while the site is being provisioned

The solution file provides a way to perform custom actions while the site is being provisioned. In the generated solution file is a folder called Site Provisioning Handler which contains a class called SiteProvisioning.cs. In this class is the OnActivated method, which enables you to add custom code. This method is called when a new site is being provisioned using the Site Definition. It accepts one parameter of type SPFeatureReceiverProperties named properties. Using this parameter you can find the SPSite and SPWeb objects by using the following code:

SPWeb web;
SPSite site;
if (properties.Feature.Parent is SPWeb)
{
    web = properties.Feature.Parent as SPWeb;
    site = web.Site;
}
Else
{
    site = properties.Feature.Parent as SPSite;
    web = site.RootWeb;
}

Create a solution package by using WSPBuilder

Several open-source and community-created tools for SharePoint Products and Technologies are publicly available on the Internet. Although Microsoft does not control, review, revise, endorse, or distribute the third-party projects on these sites, some of these tools can offer useful ways to perform common operations.

WSPBuilder is a command-line tool that can be used to automate the process of creating solution packages. WSPBuilder will recursively traverse a folder and create a SharePoint solution package, including the manifest.xml file and .wsp file, based on the files within the folder structure.

The WSPBuilder tool is available for download at Codeplex (https://go.microsoft.com/fwlink/?LinkID=106471&clcid=0x409).

Import a solution package by using the Stsadm command-line tool

Use the following procedure to import a solution file into the solution database of a Office SharePoint Server farm.

Import a solution package by using the Stsadm command-line tool

1. On a server in the farm to which you want to import a solution, on the drive where SharePoint Products and Technologies are installed, change to the directory where the Stsadm command-line tool is stored by typing the following command at a command prompt:

   cd %COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\Bin

2. Type the following command:

   stsadm -addsolution -filename <solution name>

The solution is added to the farm's solution database. To use the solution, follow the procedure in the next section in this article. For more information, see Addsolution: Stsadm operation (Office SharePoint Server).

Deploy a solution package by using the Stsadm command-line tool

You can use the deploysolution operation to deploy the solution via a command prompt.

Deploy a solution package to a single site collection

1. On a server in the farm to which you want to deploy an imported solution package, on the drive where SharePoint Products and Technologies are installed, change to the directory where the Stsadm command-line tool is stored by typing the following command:

   cd %COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\Bin

2. Type the following command:

   **stsadm –o deploysolution –name <**solution name > –url <URL name>

   where file name is the name of the solution and URL name is the URL of the Web application to which you want to deploy the imported solution.

Instead of targeting one site collection, you can optionally use the following procedure to deploy your solution to every site collection available within the server farm by using the allcontenturls parameter.

Deploy a solution package to all site collections

1. On a server in the farm to which you want to deploy an imported solution package, on the drive where SharePoint Products and Technologies are installed, change to the directory where the Stsadm command-line tool is stored by typing the following command:

   cd %COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\Bin

2. Type the following command:

   stsadm –o deploysolution –name <solution name> –allcontenturls [-time] <time to deploy> [-allowgacdeployment] [-allowcaspolicies]

   where solution name is the name of the solution.

By default, the solution is immediately deployed, but you can also schedule the deployment by using the time parameter.

The allowgacdeployment and allowcaspolicies parameters are important. The allowgacdeployment parameter enables Office SharePoint Server 2007 to deploy the assemblies in the global assembly cache. The allowcaspolicies parameter enables the creation of a custom code access security (CAS) policy file and the activation of it in the Web.config file of the targeted site collection.

For more information, see Deploysolution: Stsadm operation (Office SharePoint Server).

Deploying developed site elements by using Features

In this section:

• What is a Feature?

• When to use Features

• Create a Feature package

• Manually deploy a Feature

• Install and activate a Feature by using Stsadm

For more information about Features, see Working with Features (https://go.microsoft.com/fwlink/?LinkID=105337&clcid=0x409).

What is a Feature?

A Feature is a container of various defined extensions for Office SharePoint Server 2007 and Windows SharePoint Services 3.0, and is composed of a set of XML files which are deployed to Web servers. You can deploy a Feature as a part of a site definition or a solution package, and you can individually activate a Feature in Office SharePoint Server sites.

Features reduce the complexity involved in making simple site customizations, and are robust when upgrades are applied to a deployment. Features eliminate the need to copy large chunks of code to change simple functionality, and therefore they reduce versioning and inconsistency issues that can arise among front-end Web servers.

Features make it easier to activate or deactivate functionality in the course of a deployment, and administrators can easily transform the template or definition of a site by turning on or turning off a particular Feature in the user interface.

Features provide the following capabilities:

• Scoping semantics that enable you to specify where custom code will run.

• Ability to specify whether or not a Feature will be installed on the destination farm when it is deployed

• Ability to activate or deactivate Features at a given scope without installing or uninstalling code

• Ability to store data required by a Feature within its scope in a scoped property folder.

• The basis of a unified framework for distributed deployment of Windows SharePoint Services 3.0 and Office SharePoint Server 2007 solutions.

Items that were contained within a large site definition file in Microsoft Office SharePoint Portal Server 2003 are separate elements within Windows SharePoint Services 3.0 Features. An element is an atomic unit within a Feature. The Feature element is used in a Feature.xml file to define a Feature and to specify the location of assemblies, files, dependencies, or properties that support the Feature. A Feature includes a Feature.xml file and any number of files describing individual elements. Another Feature element from a different schema is used in an Onet.xml file to specify that a Feature be activated within a site definition.

A Feature.xml file typically points to one or more XML files whose top-level <Elements> tag contains definitions for elements that support the Feature. Elements in Windows SharePoint Services 3.0 often correspond to what were discrete nodes in the Onet.xml or Schema.xml file of the previous version. There are several types of elements —for example, a custom menu item or an event handler.

For example, A Feature could provide a "My Favorite Items" functionality that includes the following elements:

• A custom list that stores, per user, a list of favorite items, which is created as a single hidden list per workspace when the Feature is enabled.

• A custom menu item that is attached to all lists, called "Add to Favorites," which adds an item to the Favorites list.

• A Web Part that implements usage and link tracking to display the user's top 10 favorites at the top.

Each element of the Feature, by itself, may not be very useful, but when you enable the Feature on a site, all these elements add up to a complete solution.

For more information, see the following resources in the Windows SharePoint Services 3.0 SDK:

• For specific information about the file format and XML elements used in the Feature.xml file, see Feature.xml Files (https://go.microsoft.com/fwlink/?LinkId=107385&clcid=0x409).

• For information about how features affect the file format of the Onet.xml file in a site definition, see Site Definition (Onet.xml) Files (https://go.microsoft.com/fwlink/?LinkId=107386&clcid=0x409).

• For more information about Feature element types, see Element Types (https://go.microsoft.com/fwlink/?LinkID=107271&clcid=0x409).

When to use Features

You can use Features to deploy developed site elements if one or more of the following factors apply:

• Need for activation and deactivation   When you deploy site element customizations in a Feature, you can install, activate, and deactivate the Feature by using operations of the Stsadm command-line tool, or by using the object model. You can also activate and deactivate a Feature through the user interface.

• Flexibility of scope   You can activate a Feature for a single scope, including farm, Web application, site collection, and Web site.

• Ease of distributed deployment   A Feature is easy to deploy to multiple server farms.

• Deep control through the Feature object model   The Feature object model enables you to specify the list of installed features within a given scope, and to control whether features are enabled at the farm and site levels

As shown in the deployment diagrams in the article Customization scenarios, you can use Features to deploy developed site element customizations between developer workstations and an integration farm, and between an integration farm and authoring client workstations and pilot or production farms.

Create a Feature package

When you create a custom Web page in Office SharePoint Server 2007, the ASPX page can belong only to the root site collection of the server running Office SharePoint Server 2007. To create a page under a site collection that is not at the root, you must deploy the custom Web page as a SharePoint Feature. A SharePoint Feature requires two simple XML files and is deployed by using the Stsadm command-line tool — a process which you can automate with a batch file.

Create a custom Feature

1. Create a Feature.xml file. The following is an example Feature.xml file, which is necessary for giving the feature a unique ID and pointing to the Module.xml file.

   <?xml version="1.0"?>
   <Feature Id="8C4DD0CB-5A94-44da-9B7F-E9ED49C2B2DC" Title=
   "Custom Web page"
   Description="This simple example feature adds an ASPX page 
   with a hosted XmlFormView control" 
   Version="1.0.0.0" Scope="Web"
   xmlns="https://schemas.microsoft.com/sharepoint/">
   <ElementManifests>
       <ElementManifest Location="Module.xml"/>
   </ElementManifests>
   </Feature>
   

2. Create a Module.xml file. The following is an example Module.xml file, which contains information about the page or pages that are part of the solution.

   <?xml version="1.0"?>
   <Elements xmlns="https://schemas.microsoft.com/sharepoint/">
       <module name="file" url="" path="">
           <file url="XmlFormViewPage.aspx" type="ghostable"> </file>
       </module>
   </Elements>
   

3. Change the file url value to the name of your ASPX page, and then run the command-line operations as described in Install and activate a Feature by using the Stsadm command-line tool. You can create a batch file and run these command-line operations sequentially.

4. Perform the following actions:

   1. Create a folder under the Features folder on your server computer, typically located at %COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\TEMPLATE\FEATURES.

   2. Add your custom ASPX page to this folder.

   3. Create the Feature.xml and Module.xml files based on the examples shown in the previous section, and add them to the same location.

To install and activate a Feature after it has been deployed, see Install and activate a Feature by using the Stsadm command-line tool later in this article.

Manually deploy a Feature

To implement a Feature, you add a subfolder containing a Feature definition within the Features setup directory (in this example, Local_Drive:\%COMMONPROGRAMFILES%\Microsoft shared\Web server extensions\12\TEMPLATE\FEATURES). The Feature subfolder includes a Feature.xml file that defines the base properties of the Feature and lists elements bound to it, such as XML files containing element manifests and any other supporting files. A Feature folder can contain a Feature.xml file only, or it can contain a Feature.xml file and any number of supporting element files, including XML files, but also .aspx, .htm, .xsn, .resx, .dll, and other file types.

After creating the Feature folder, you can install and activate the Feature by using Stsadm command-line operations, or by using the object model. You can also activate a Feature on the Site Collection Features page or on the Site Features page of the site collection or site on which you want to activate the Feature. Installing a Feature makes its definition and elements known throughout a server farm, and activating the Feature makes the Feature available at a particular scope.

Install and activate a Feature by using the Stsadm command-line tool

You install Features in the 12\Template\Features directory, with each Feature in its own subdirectory. At the root of this folder, a Feature.xml file defines the contents of the Feature.

You must install individual Features before you can use them. To do this, run the following command at the command prompt:

stsadm -o installfeature-filename <relative path> -name <feature folder> [-force]

For more information, see Installfeature: Stsadm operation (Office SharePoint Server).

In addition to installing a Feature, you must activate it before you can use it (unless the Feature is scoped to the farm, which means it is activated automatically).

To activate a Feature, run the following command:

stsadm -o activatefeature -filename <relative path> -name <feature folder> -id <feature ID> [-url] <URL name> [-force]

For more information, see Activatefeature: Stsadm operation (Office SharePoint Server).

To uninstall a Feature so that its definition is no longer available within a server farm, you can use the uninstall operation. For more information, see Uninstallfeature: Stsadm operation (Office SharePoint Server).

After uninstalling a Feature, reset Internet Information Services (IIS) so that changes can take effect.

To deactivate a Feature so that it becomes inactive at its originally assigned scope without uninstalling it, you can use the deactivate operation. For more information, see Deactivatefeature: Stsadm operation (Office SharePoint Server).

Download this book

This topic is included in the following downloadable book for easier reading and printing:

• Design and build sites for Office SharePoint Server 2007

See the full list of available books at Downloadable books for Office SharePoint Server 2007.

See Also

Concepts

Deploy customizations
Deploying authored site element customizations
Solution package components