Feature Upgrade Object Model

Article
10/20/2016

Applies to: SharePoint Foundation 2010

To provide Feature upgrade capability, new types and members have been added to the Microsoft SharePoint Foundation object model. These include:

FeatureUpgrading event
Version property
QueryFeatures methods
Upgrade method

FeatureUpgrading Event

Feature receivers (SPFeatureReceiver) can now be used to handle FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) events. You can implement your own custom Feature receiver to upgrade Feature instances.

FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) parameters include properties of the current executing context, the name of the custom upgrade action to execute, and a dictionary of custom upgrade action parameters.

For an example that shows how to use the FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) method, see How to: Use Upgrade Code to Activate a Feature with Dependencies.

Version Property

The existing SPFeatureDefinition class already has a Version property, and the SPFeature class in SharePoint Foundation also provides a new Version. However, the current Feature version that is specified in the Feature.xml file is the version that is defined in the SPFeatureDefinition class. Version is a unique version class that is associated with a Feature instance at a specified scope, which may not match the Feature definition version.

An object at a specific scope, such as an SPWebApplication or SPSite object, is determined to need upgrade if one or more of the Features associated with the object has a lower version number than what is specified in the Feature.xml file that is associated with that Feature instance.

The version has the format xxxx. xxxx. xxxx. xxxx where x is a single digit. If the Feature.xml file does not specify a Version attribute, "0.0.0.0" is the default version.

Note

SharePoint Foundation does not allow "short" versions, where less than four numbers of a version are specified (such as, 1.0); if this occurs, an exception is thrown.

QueryFeatures Method

The new QueryFeatures methods allow you to query Features in different scopes by using a set of filtering criteria. The SPWebService, SPWebApplication, SPContentDatabase, and SPSite classes each provide a QueryFeatures method, whose overloads allow you to specify different criteria for determining which Feature instances result set to return.

SPWebService -- Find activated Feature instances in the server farm that conform to filtering criteria.
SPWebApplication -- Find Web application, site collection, and Web site-scoped Features that conform to the specified filtering criteria. Query is run across all content databases in the Web application object and the returned collection is ordered by content database.
SPContentDatabase -- Find Features in the content database that are scoped for site collection and Web site and that conform to the specified filtering criteria. The collection that is returned is ordered with respect to Web site hierarchy. For example, parent Web site Features are represented before child Web site Features, and the hierarchy is traversed from the top down.
SPSite -- Find all site collection and Web site-scoped Features that conform to the specified filtering criteria. The returned collection is ordered with respect to Web site hierarchy. Parent Web site Features are represented before child Web site Features, and the hierarchy is traversed from the top down. Overloads of the QueryFeatures method for this class are available in the new client-side object models.

Overloads

The following four overloads of the QueryFeatures method are provided for each of the classes listed above:

Return all Feature instances with the specified scope. You can use the needsUpgrade parameter to return all Features that need upgrade.

public Microsoft.SharePoint.SPFeatureQueryResultCollection 
QueryFeatures(Microsoft.SharePoint.SPFeatureScope scope, bool needsUpgrade)

Return all Feature instances with the specified Feature ID. You can use the needsUpgrade parameter to return all Features that need upgrade.
```
public Microsoft.SharePoint.SPFeatureQueryResultCollection 
QueryFeatures(System.Guid featureId, bool needsUpgrade)
```

Return all Feature instances with the specified Feature ID and version number.

public Microsoft.SharePoint.SPFeatureQueryResultCollection 
QueryFeatures(System.Guid featureId, System.Version featureVersion)

Return all Feature instances with the specified Feature ID.

public Microsoft.SharePoint.SPFeatureQueryResultCollection    
QueryFeatures(System.Guid featureId)

The SPFeatureQueryResultCollection class is used to enumerate the Features returned through a QueryFeatures operation.

During upgrade, the QueryFeatures method determines if a Feature instance is outdated when it finds an instance version number that is lower than the current Feature.xml definition version number. Based on the UpgradeActions directives in the Feature.xml file, upgrade is called for each Feature instance that requires it. After successful upgrade of a Feature instance, its version number is then updated to match the Feature.xml file definition version number.

Upgrade Method

The SPFeature class now provides an Upgrade(Boolean) method to perform upgrade for a Feature instance at all scopes: Farm, WebApplication, Site, and Web.

When called on a dependent Feature instance, the QueryFeatures method first upgrades the highest level Feature instance in the relevant hierarchy and then upgrades all Feature instances that depend on that Feature. This hierarchical upgrade process assures that all dependent Feature instances remain in sync with the Feature instance they depend upon.

Important

Do not call the Upgrade(Boolean) method from within a Feature upgrade event receiver. For example, do not call this method on the Features that can be obtained through code such as the following:

SPFeatureQueryResultCollection queryResults = myWebService.QueryFeatures(myScope, true);

IEnumerator<SPFeature> featureEnumerator = queryResults.GetEnumerator();