Feature.xml Changes

Article
10/20/2016

Applies to: SharePoint Foundation 2010

The new <UpgradeActions> section in a Feature.xml file specifies upgrade actions that you can apply to a specified Feature.

You can place the <UpgradeActions> section at the beginning or end of the Feature.xml file, within the contents of the <Feature> element. This section allows you to specify upgrade actions for differing ranges of upgrade, and include a list of upgrade actions that apply to a specified range. Upgrade definitions always upgrade a Feature to the version that is declared in the <Feature> element.

The following code shows a sample <UpgradeActions> section that can be defined in a Feature.xml file.

<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>

The <UpgradeActions> section specifies how to upgrade a Feature instance. Common upgrade scenarios can be accomplished declaratively by simply modifying the Feature.xml file, while more advanced scenarios may require that you implement the FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) method to perform custom Feature upgrade logic. For information about declarative elements, see "Scope and Provisioning of Element Manifests."

The <UpgradeActions> element can contain the following sub-elements:

<CustomUpgradeAction> — Allows you to execute custom code when a Feature instance is being upgraded. When an action is specified in an upgrade action sequence, Microsoft SharePoint Foundation calls the FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) method synchronously with other upgrade actions, in order of declaration.
<VersionRange> — Specifies a version range to which specified upgrade actions apply.
<ApplyElementManifests> — Adds a new element to an existing Feature. When a Feature is upgraded, provisions all non-declarative elements that are referenced in the specified element manifests.
<AddContentTypeField> — Adds a new field to an existing provisioned content type. Propagates the change from the site content type to all child lists and content types within the site. For example:
```
<AddContentTypeField 
  ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7" 
  FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}" 
  PushDown="TRUE" />
```
In most cases, the values of the ContentTypeId and FieldId attributes are specified in the Elements.xml file where the content type and field are defined.
<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.

To help you work with versioned Feature dependencies, the MinimumVersion attribute has been added to the <ActivationDependency> element, which is used when a Feature depends on another Feature that must have a version number greater than or equal to the MinimumVersion.

Scope and Provisioning of Element Manifests

The following table shows the scopes at which a specific Feature element is valid and whether the element is provisioned when the Feature is activated or unprovisioned when the Feature is deactivated.

Feature Element	Scope	Provisioning
Content Type	Site Collection	Provisioned/unprovisioned
Content Type Binding	Site Collection, Web Site	Provisioned/not unprovisioned
Control	Farm, Web Application, Site Collection, Web Site	Not provisioned at all (declarative)
Custom Action	Farm, Web Application, Site Collection, Web Site	Not provisioned at all (declarative)
Custom Action Group	Farm, Web Application, Site Collection, Web Site	Not provisioned at all (declarative)
Document Convertor	Web Application	Provisioned/unprovisioned
Feature/Site Definition Association	Farm, Web Application, Site Collection	Not provisioned at all (declarative)
Field	Site Collection	Provisioned/unprovisioned
Hide Custom Action	Farm, Web Application, Site Collection, Web Site	Not provisioned at all (declarative)
List Definition	Site Collection, Web Site	Not provisioned at all (declarative)
List Instance	Site Collection, Web Site	Provisioned/not unprovisioned
Module	Site Collection, Web Site	Provisioned/not unprovisioned
Receiver	Site Collection, Web Site	Provisioned/unprovisioned
Workflow Template	Site Collection	Not provisioned at all (declarative)

Note

The preceding table does not include representation of the following new element types: Cmdlet, UserMigrator, WebPartAdderExtension, WebTemplate, and WorkflowAssociation.

As seen in the table, the <CustomAction> element is available at all scopes: Web (Web site), Site (site collection), WebApplication, and Farm (server farm). It is a declarative element that is neither provisioned nor unprovisioned, which means that it is cached directly from the Feature XML definition into memory, without any provisioning logic occurring during Feature activation. For this reason, after you activate the Feature and navigate to pages that contain the custom action, the custom action is loaded from the cache and then displayed on that page. The Field element is only valid at site collection scope. It is provisioned on activation (site column created) and unprovisioned on deactivation (site column removed). The <ListInstance> element is valid at Web and site collection scopes. It is provisioned on activation (list instance created) but is not unprovisioned on deactivation (list instance not deleted).

Note

Declarative elements that are specified in the <ElementManifests> section are provisioned during Feature activation, but they are ignored in Feature upgrade. Consequently, the way to add declarative elements on upgrade is to place them within the <ApplyElementManifests> section. You must run iisreset at the command line before calling upgrade, in order to refresh the cache, or else you must use a solution deployment upgrade.

Feature.xml Changes

Scope and Provisioning of Element Manifests

Additional resources