SharePoint Feature Upgrade:Introduction

Hi,

Every SharePoint Feature has a version number(by default "0.0.0.0") 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.

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 upgrade infrastructure queries for the set of Feature instances that need upgrade and then upgrades each of those Feature instances. The order in which the up-gradation happens is as follows:

1. Server farm level,


2. Web application level


3. Site collection


4. Web sites level(starting from root web level to child level webs)

We can perform the following kinds of modular upgrades to Features in SharePoint Foundation:

• Define upgrade definitions for new Feature versions.


• Provision a list instance as part of a Feature upgrade


• Create separate upgrade action sets, based on the Feature version, that  remove different sets of files.


• Apply settings to site collections where a particular Feature is activated.

FeatureUpgrading Event:

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

FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary(Of 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.

Feature.xml Changes

In order to perform the custom action we must add a feature <UpgradeActions> section in a Feature.xml file. Below is the example of this tag

<UpgradeActions
  ReceiverAssembly="MyFeatureReceiver,
  Version=1.0.0.0,
  Culture=neutral,
  PublicKeyToken=2f2197d99d6e2871"
  ReceiverClass="FeatureReceiver.TestFeatureReceiver">
  <CustomUpgradeAction
    Name="DeleteField">
    <Parameters>
      <Parameter
        Name="FieldName">Address3
      </Parameter>
    </Parameters>
  </CustomUpgradeAction>
  <VersionRange
    BeginVersion="2.0.0.0"
    EndVersion="5.0.0.0">
      <!-- Here you specify other upgrade actions to apply to Feature instances whose versions are within the range 2.0.0.0 to 5.0.0.0 -->
  </VersionRange>
</UpgradeActions>

• <CustomUpgradeAction> — This is used to execute custom code while feature is being upgraded.


• <VersionRange> — Specifies a version range to which specified upgrade actions apply.


• <ApplyElementManifests> — Adds a new element to an existing Feature.


• <AddContentTypeField> — Adds a new field to an existing provisioned content type.


• <MapFile> — Allows you to map an uncustomized file to a different location on the front-end Web server. You can use the FromPath and ToPath attributes to rename a file in a Feature (for example, <MapFile FromPath=”oldname.gif” ToPath=”newname.gif” />, but you can also use MapFile to move a file. In this case, the FromPath and ToPath attributes specify paths that are relative to the TEMPLATE directory. For example, if a Feature named "MyFeature" has .gif files installed in a "Gifs" directory (such as, %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES\MyFeature\Gifs\basketball.gif), and in version 2 you want to rename the directory from “Gifs” to “Images”, then <MapFile FromPath=”Gifs\ball.gif” ToPath=”Images\basketball.gif” /> can be used to move the files.

Things to be remembered:

1. Increase the version number when you update a Feature.


2. Keep version numbers of your Feature independent from Microsoft product versions


3. Increment a major version number to the current major product version the first time you create or change a Feature during a new development cycle


4. Increment the build version for subsequent changes during a development cycle.


5. For an initial service pack change, increment the minor version.

Adding new elements to an existing Feature:

1. Add a Version attribute


2. Add an <UpgradeActions> section


3. Create a new Elements.xml file that contains all the new elements


4. Reference the Elements2.xml file in both the main <ElementManifests> section and the <ApplyElementManifests> section within the <UpgradeActions> section.

<UpgradeActions
    ReceiverAssembly="MyFeatureReceiver, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3ef91b1292056a22" 
    ReceiverClass="MyFeatureReceiver.MyReceiver">
    <VersionRange EndVersion="2.0.0.0">
      <CustomUpgradeAction Name=”ActivateFeature”/>
      <ApplyElementManifests>
        <ElementManifest Location="Elements2.xml"/>
      </ApplyElementManifests>
    </VersionRange>
  </UpgradeActions>

---

Error Handling: 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.

There is very good tool you can use to upgrade the feature created by Chris O'Brien. You can download and deploy this tool from codeplex

For more reference: feature upgrade

Thanks

Mohit