Feature Upgrade Overview

Applies to: SharePoint Foundation 2010

In Microsoft SharePoint Foundation, every Feature has a version number that is specified in the corresponding Feature.xml file. When a Feature is activated at a specified scope, a Feature instance is created that is associated with that version of the Feature. Feature versioning in SharePoint Foundation allows Features and their associated instances to be easily tracked. Then, when you deploy a new version of a Feature, SharePoint Foundation detects that the associated Feature instance also needs an upgrade because the instance version number is lower than the new version number specified in the current Feature.xml file.

Note

It is best practice to never place a Feature file in the FEATURES folder apart from solution deployment or solution upgrade files, because Feature upgrade is an advanced deployment option that does not validate the Feature XML during deployment.

When you run Feature upgrade, Feature instances that need to be upgraded will also be upgraded according to the upgrade actions that are specified in the new Feature.xml file. SharePoint Foundation uses new QueryFeatures methods that can be applied to top-level objects, such as SPWebApplication and SPSite, to determine what Feature instances need to be upgraded, based on their version numbers. The new Feature.xml file has a section that can be used to specify the upgrade actions that are required to upgrade a particular Feature instance from an earlier version to the most current version. The upgrade infrastructure queries for the set of Feature instances that need upgrade and then upgrades each of those Feature instances. This activity can involve declarative upgrade actions as well as custom upgrade code. In SharePoint Foundation, the version number is tracked for each Feature instance.

Features are upgraded in the following order: first at the server farm level, next at the Web application level, then site collection, and finally, at specific Web sites. At the Web site level, Feature instances are upgraded starting with root Web sites and progressing downward through the hierarchy of child Web sites. Features are upgraded based on the order of dependency, that is, dependent Features are upgraded after the Features that they depend upon.

When an error occurs during upgrade, the upgrade stops for the specified Feature instance and the error is recorded, both in ULS logs and also in an Upgrade.log file. (Typically, ULS logs contain more information about the error.) Meanwhile, the upgrade continues to run on other Feature instances. After the initial upgrade is complete, and before restarting the process, administrators have the opportunity to discover and resolve issues that caused any Features to fail upgrade. Then, when the upgrade process is initiated again, SharePoint Foundation repeats all upgrade actions for the Features that initially failed, thus allowing the upgrade process to be successfully completed for all Features and Feature instances.

Note

Feature upgrade runs under Farm Administrator credentials.