Export (0) Print
Expand All

Feature.xml Changes

SharePoint 2010

Published: May 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.

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

Community Additions

ADD
Show:
© 2014 Microsoft