Creating a Custom Feature in SharePoint Server 2007
Summary: Features in Microsoft Office SharePoint Server 2007 allow you to easily package up functionality that can be deployed and installed across the server farm. This article walks you through the steps of creating and installing a custom Feature. (10 printed pages)
Frank Rice, Microsoft Corporation
February 2008
Applies to: Microsoft Office SharePoint Server 2007, Microsoft Visual Studio 2005
Contents
Overview
Exploring the Components of a Feature
Creating Your Own Custom Feature
Conclusion
Additional Resources
Overview
Features are a major enhancement to the template framework of Microsoft Office SharePoint Server 2007 (MOSS). Features allow you to test, deploy, and activate custom functionality inside Office SharePoint Server 2007 and provide a way to make functionality available across your server farm. This functionality can be custom workflows, content types, modifications to the user interface, or new templates for lists and document libraries. For example, you can roll out the definition of a custom document library to any number of team sites by packaging it up as a Feature, complete with metadata expressed in the Collaborative Markup Language (CAML) in the schema. You can package the Feature up as a SharePoint solution and provide it to an administrator, where it can be installed and deployed as a unit.
Another benefit of using Features is in the use of site definition (ONET.xml) files. ONET.xml files provide Windows SharePoint Services with information about the navigation, lists, and document libraries that users can create. In the previous version of SharePoint, ONET.xml files have a tendency to get very large. With the advent of Features, the ONET.xml file shrinks because Features can now contain the information that was previously defined in the ONET.xml file.
In this article, you will create a custom Feature but before this, it might be helpful to review some of the basics of Features.
Exploring the Components of a Feature
Features are typically stored on the SharePoint server at C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. Each Feature has its own sub-directory that resides in this directory. Inside each Feature's sub-directory, you will find, as a minimum, a header file named feature.xml. The feature.xml file points to a manifest file that tells SharePoint where to find the code and XML that defines the Feature. The feature.xml file contains the Feature element that specifies the location of assemblies, files, dependencies, or properties that support the Feature. Optionally, the Feature element may point to an XML file that contains an Element element which defines the components and types that make up the Feature.
The following are samples of the components that comprise a Feature.
The Feature.xml File
The feature.xml file defines the metadata associated with a Feature.
<?xml version="1.0" encoding="utf-8" ?>
<Feature Id="00BFEA71-E717-4E80-AA19-D0CBE412FFA6"
Title="Hello World Feature"
Description="$Resources: core,documentlibraryDesc;"
Version="1.0.0.0" Scope="Web" Hidden="FALSE"
DefaultResourceFile="documentLibrary"
...ImageUrl="menuprofile.gif"
xmlns="https://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="elements.xml" />
</ElementManifests>
</Feature>
The following metadata is contained in the <Feature> element in this XML file.
ID: The GUID that uniquely identifies the Feature. This value must be unique across the server farm.
Title: The name of the Feature. In an actual scenario, you will see the name of the Feature displayed on the Site Features web page inside the Site Settings section for a given SharePoint site.
Description: The description of the Feature. Notice that in this sample, the description is retrieved from a resource file (a file with a .resx extension) instead of hard-coded in the file. The strings are stored as key/value pairs within the resource file. The following is a segment from a resource file named documentLibrary.resx that provides the description of the sample Feature.
<root> <Data Name="documentlibraryDesc"> <Value>A custom publishing page for Northwind Traders.</Value> </Data> </root>Version: The version of the Feature. This value can be incremented for successive versions of the Feature.
**Scope:**Web or Site are the typical values. The scope defines the context in which the Feature can be activated or deactivated. Setting the scope equal to Web means that the Feature can be activated or deactivated within the context of the site. A setting of Site means that the Feature can be activated or deactivated within the scope of a site collection. The scope is set to the site collection displayed to the administrator in the Site Collection Features page. There are also WebApplication and Farm values.
**Hidden:**TRUE or FALSE are allowable values here. This setting specifies if the Feature is visible in the list of Features on the Site Features web page. Setting the attribute to TRUE makes the Feature visible to users who want to activate it. Hidden Features must be activated either from the command line, in custom code, or through the dependency of another Feature.
DefaultResourceFile: Specifies the central location for settings and other items that may change frequently.
ImageUrl: Points to an image file that will be displayed next to the Feature in the user interface.
**<ElementManifests>**element: The container element for <ElementManifest> elements.
<ElementManifest> element: Contains the location of the manifest file that contains the different <Elements> elements that this Feature implements. The path to sub-directories and files is a relative path.
The following is a code segment from the elements.xml manifest file that is implemented by this particular Feature. The manifest file contains details of the different components or actions that make up a Feature. For example, the manifest for an event handler might say, for lists of the specified type, use the class defined in this specified assembly to respond to this specified list item event type, for example, the ItemUpdated event. Here, the manifest file defines a field that might be used in a list column, for example.
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<Field ID="{0B9E3314-3F9F-2aa8-4BCD-7CB89A6FB32D}"
Name="ProductName"
SourceID=https://schemas.microsoft.com/sharepoint/v3
StaticName="ProductName"
Group="ProductColumns"
DisplayName="Product Name"
Type="Text">
</Field>
</Elements>
In this markup code, a field is identified by a GUID and name. The group and display name identify the Feature and the values that appear in the column setup screen on the SharePoint site. These values could just as easily be retrieved from a resource file. And finally, every field must be associated with a Windows SharePoint Services field type.
Note
Groups typically specifies a section or area in the user interface (UI).
Install the Feature
After you have created the feature.xml and elements.xml files in a folder, you then need to install and activate the Feature. The process involves three steps.
To install and activate a Feature
Copy the folder containing the two files to the Windows SharePoint Services FEATURES directory.
Run the STSADM.EXE utility to install the Feature.
Run the STSADM.EXE utility to activate the Feature in the context of a Windows SharePoint Services site.
Creating Your Own Custom Feature
In the following procedure, you create a content type for lists that defines columns for storing information about widgets. For the purpose of this example, this content type is pretty basic, containing only three text fields.
Name
Version
Description
Creating the content type as a Feature allows Administrators to make the type available to all sites in the server farm without adding the content type manually.
To create the list column definition file
Create a working folder to hold the files defining the Feature; name the folder CustomWidgetColumns.
Next, create the XML file that contains the list column definitions. A good way to see what you need to create columns is to look at the default columns created by SharePoint. You can find examples of column definitions at the following location.
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES
The default SharePoint site columns file is located in this file.
\TEMPLATE\FEATURES\fields\fieldswss.xml
Now, create a folder in your working folder called fieldsWidget. In the fieldsWidget folder, create an XML file named fieldsWidget.xml and paste the following XML into it.
<?xml version="1.0" encoding="utf-8" ?> <Elements xmlns="https://schemas.microsoft.com/sharepoint/"> <Field ID="{DA7A42EE-CDD5-4ec4-A641-2D773B320DA5}" Name="Name" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="Name" Group="Widget Data" Type="Text" Hidden=”FALSE” DisplayName="Widget Name" /> <Field ID="{C1005435-A46E-32ea-ABC1-1C37DA453623}" Name="Version" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="Version" Group="Widget Data" Type="Text" Hidden=”FALSE” DisplayName="Versions" /> <Field ID="{99C3A33C-AC20-43ca-8900-AE4E1D22AEE6}" Name="Description" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName=" Description" Group="Widget Data" Type="Text" Hidden=”FALSE” DisplayName="Description" /> </Elements>In this sample, the <Elements> element is the container element for the fields that comprise the list columns. The <Field> element contains the attributes that define the metadata for each column. The ID attribute of each field element is a 32 character GUID. The easiest way to create a GUID is with the guidgen.exe utility that comes with Microsoft Visual Studio. This is the path to the utility.
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\guidgen.exe
The Group attribute defines which group the site columns are placed in. The group is the value displayed in the Select site columns from dropdown on the SharePoint site. If you use the name of a group that does not already exist, SharePoint will automatically create one for you. The Type attribute defines the data type for the field. This attribute is required for content types. To see how to create different data types, look in the fieldswss.xml file.
Finally create the feature.xml file in the fieldsWidget folder and paste the following XML into it.
<?xml version="1.0" encoding="utf-8" ?> <Feature Id="3C637DAA-0239-40a1-A677-F0422E10741A" Title="Widget Data Site Columns" Description="Installs columns designed to manage information about widgets." Version="12.0.0.0" Hidden=”FALSE” Scope="Site" DefaultResourceFile="core" xmlns="https://schemas.microsoft.com/sharepoint/"> <ElementManifests> <ElementManifest Location="fieldsWidget.xml" /> </ElementManifests> </Feature>Notice that the Id attribute of the <Feature> element does not have the "{}" braces at the beginning and end of the GUID as the fieldsWidget.xml file did. Note that some Id attributes in SharePoint are formatted with the "{}" characters and some are without.
The Hidden attribute setting specifies whether the Feature is visible in the list of Features on the Site Features web page. Here, the attribute is set to TRUE which makes the Feature visible to users who want to activate it. The Scope attribute is set to Site. That means this Feature will be installed and activated for the entire site collection. And finally, the Location attribute of the <ElementManifest> element is set to the manifest file you created for the Feature. The location of the file is relative to the 12\TEMPLATE\FEATURES folder.
Now that defining the site columns for the Feature is completed, you need to create a file for the Feature content types that specify the components of the Feature. The XML markup for the file is shown here.
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="https://schemas.microsoft.com/sharepoint/">
<ContentType ID="0x0100D76B3817D18C4a97D3B1742271806CCF"
Name="Widget Data"
Group="Widgets"
Description="Designed to facilitate the storage of widget information."
Version="0">
<FieldRefs>
<FieldRef ID="{DA7A42EE-CDD5-4ec4-A641-2D773B320DA5}" Name="Name" />
<FieldRef ID="{C1005435-A46E-32ea-ABC1-1C37DA453623}" Name="Version" />
<FieldRef ID="{99C3A33C-AC20-43ca-8900-AE4E1D22AEE6}" Name="Description" />
</FieldRefs>
</ContentType>
</Elements>
One thing to notice here is the ID attribute of the <ContentType> element. The ID is a combination value that consists of a number that indicates what other content types it inherits from and a GUID. The "0x0100" portion of the ID tells SharePoint that this content type inherits the item content type. The remainder of the ID is a standard 32 character GUID.
Note
For more information, see the topic Content Type IDs.
The <FieldRef> elements reference the site columns you defined in the fieldsWidget.xml file. The ID and Name attributes must match the values of the site column you are referencing.
To get a better idea of how to create the site content types, review the default content types created by SharePoint in the following file.
\TEMPLATE\FEATURES\ctypes\ctypeswss.xml
You can find documentation on the general xml schema you use to define the content type in the topic Content Type Definition Schema.
Now that you have the XML markup for the content type, it is time to create the file as well as the Feature file for the content types.
To create the content types manifest and Feature files
Create a folder in your working folder named ctypesWidget.
In the ctypesWidget folder, create an XML file named ctypesWidget.xml and paste the content type XML markup discussed previously into it.
As you did with the site columns definition, you need to create a feature.xml file in the ctypesWidget folder and paste the following XML into it.
<?xml version="1.0" encoding="utf-8" ?> <Feature Id="9AA45361-A65F-41df-63D3-676B412E3FD6" Title="Widget Data Content Types" Description="Installs content types designed to manage information about widgets." Version="12.0.0.0" Hidden="FALSE" Scope="Site" DefaultResourceFile="core" xmlns="https://schemas.microsoft.com/sharepoint/"> <ElementManifests> <ElementManifest Location="ctypesWidget.xml" /> </ElementManifests> <ActivationDependencies> <!-- Installs the site columns that hold widget data --> <ActivationDependency FeatureId="3C637DAA-0239-40a1-A677-F0422E10741A"/> </ActivationDependencies> </Feature>By now, you should have a good idea of the meaning of each line in this file. Notice that you are referencing the widget site columns Feature as an activation dependency. This ensures that the correct site columns are present before the widgets content type is installed.
Now that both of the Features are complete, copy the ctypesWidget and the fieldsWidget folders to the Features folder on your SharePoint server at the following location.
C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES
Next, you need to install and activate the Features, starting with the content type.
To install and activate the custom Feature
Open a command prompt by clicking Start, clicking Run, and then typing cmd.
Run the following commands, in sequence.
cd "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN"
stsadm –o installfeature –filename ctypesWidget\feature.xml
Note
The location of the feature.xml file in the above command is relative to the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES folder.
Repeat the installfeature command for the feature.xml file in the fieldsWidget folder.
In addition to installing the Feature, you must activate it before you can use it (unless the Feature is Farm scoped, which means it is activated automatically).
Note Activate the fieldsWidget Feature first and then the ctypesWidget Feature. Also note that you should substitute the address of your server in place of https://localhost in the following command.
To activate the Feature, run the following command at the command prompt.
stsadm –o activatefeature –name fieldsWidget -url "http:\\localhost"
Repeat the command for the ctypesWidget folder.
Now it is time to test the Feature.
To test the Feature
Open your SharePoint Web site in an Internet browser.
Display an existing list or create a new list.
In the list display screen, click Settings, and then click List Settings.
In the Columns section, click Add from existing site columns.
Click the Select site columns from dropdown, and then click Widget Data.
In the Available site columns box, highlight the three columns, and then click the Add button as shown in Figure 1.
Figure 1. Adding the custom columns to the list
.gif "Adding the custom columns to the list")
Click OK and then navigate back to the list. The three new columns are displayed on the right-side of the screen (see Figure 2).
Figure 2. Displaying the new columns
.gif "Displaying the new columns")
And finally, you may want to remove the Feature. If the Feature is Web scoped or Site scoped, you must deactivate Features before uninstalling them. If the Feature is WebApplication scoped or Farm scoped, this step is not necessary.
To deactivate and uninstall the Feature
To deactivate the Feature, run the following command at a command prompt.
stsadm –o deactivatefeature –filename "ctypesWidget\feature.xml" -url "http:\\localhost"
To uninstall the Feature so that its definition is no longer available within a server farm, run the following command.
stsadm -o uninstallfeature -filename "ctypesWidget
Repeat the procedures for the fieldsWidget Feature files.
After uninstalling the Feature, reset Internet Information Services (IIS) so that the changes take effect. At the command prompt, type iisreset.
Conclusion
Features provide a level of reusability by providing you with a means to package and deploy functionality as a unit. You can install the Feature at the level of a server farm and then active it only when needed. This has the additional benefits of allowing you to deploy updates to all Web front-end machines in one operation, more easily applying source-control to site resources, and allowing less-technical people to roll-out or roll-back changes, if required.
Additional Resources
You can find more information about SharePoint Features discussed in this article at the following locations.