Feature.xml 更改
上次修改时间: 2015年3月9日
适用范围: SharePoint Foundation 2010
Feature.xml 文件中新增的 <UpgradeActions> 节指定可应用于指定功能的升级操作。
可以将 <UpgradeActions> 节放置在 Feature.xml 文件的开头或末尾,使其位于 <Feature> 元素的内容中。通过该节,您可以为不同的升级范围指定升级操作,并且可以包含应用于指定范围的升级操作列表。升级定义始终将功能升级到 <Feature> 元素中声明的版本。
以下代码显示可在 Feature.xml 文件中定义的示例 <UpgradeActions> 节。
<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>
<UpgradeActions> 节指定如何升级功能实例。可通过直接修改 Feature.xml 文件以声明方式完成常见升级方案,但是更高级的方案可能需要实现 FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) 方法以执行自定义功能升级逻辑。有关声明性元素的信息,请参阅"元素清单的范围和设置"。
<UpgradeActions> 元素可以包含下列子元素:
<CustomUpgradeAction> — 允许您在升级功能实例时执行自定义代码。如果在升级操作序列中指定了操作,则 Microsoft SharePoint Foundation 会按照声明顺序与其他升级操作同步调用 FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) 方法。
<VersionRange> — 指定已指定的升级操作应用于的版本范围。
<ApplyElementManifests> — 向现有功能添加新元素。升级功能时,设置在指定的元素清单中引用的所有非声明性元素。
<AddContentTypeField> — 向现有的已设置内容类型添加新字段。将更改从网站内容类型传播到网站中的所有子列表和内容类型。例如:
<AddContentTypeField ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7" FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}" PushDown="TRUE" />
在大多数情况下,ContentTypeId 和 FieldId 属性的值在定义内容类型和字段的 Elements.xml 文件中指定。
<MapFile> — 允许您将未自定义的文件映射到前端 Web 服务器上的其他位置。可以使用 FromPath 和 ToPath 属性重命名功能中的文件(例如,<MapFile FromPath="oldname.gif" ToPath="newname.gif" />),还可以使用 MapFile 移动文件。在这种情况下,FromPath 和 ToPath 属性指定相对于 TEMPLATE 目录的路径。例如,如果名为"MyFeature"的功能在"Gifs"目录中安装了 .gif 文件(如 %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES\MyFeature\Gifs\basketball.gif),并且您要在版本 2 中将目录从"Gifs"重命名为"Images",则 <MapFile FromPath="Gifs\ball.gif" ToPath="Images\basketball.gif" /> 可用于移动这些文件。
为了帮助您处理已进行版本控制的功能依赖关系,<ActivationDependency> 元素增加了 MinimumVersion 属性,该属性在功能所依赖的另一功能的版本号必须大于或等于 MinimumVersion 时使用。
元素清单的范围和设置
下表显示特定功能元素的有效范围,以及在激活功能时是否设置元素或在停用功能时是否取消设置元素。
功能元素 |
范围 |
设置 |
---|---|---|
内容类型 |
网站集 |
设置/取消设置 |
内容类型绑定 |
网站集、网站 |
设置/不取消设置 |
控件 |
场、Web 应用程序、网站集、网站 |
根本不设置(声明性) |
自定义操作 |
场、Web 应用程序、网站集、网站 |
根本不设置(声明性) |
自定义操作组 |
场、Web 应用程序、网站集、网站 |
根本不设置(声明性) |
文档转换器 |
Web 应用程序 |
设置/取消设置 |
功能/网站定义关联 |
场、Web 应用程序、网站集 |
根本不设置(声明性) |
字段 |
网站集 |
设置/取消设置 |
隐藏自定义操作 |
场、Web 应用程序、网站集、网站 |
根本不设置(声明性) |
列表定义 |
网站集、网站 |
根本不设置(声明性) |
列表实例 |
网站集、网站 |
设置/不取消设置 |
模块 |
网站集、网站 |
设置/不取消设置 |
接收器 |
网站集、网站 |
设置/取消设置 |
工作流模板 |
网站集 |
根本不设置(声明性) |
备注
前面的表不包含以下新元素类型的说明:Cmdlet、UserMigrator、WebPartAdderExtension、WebTemplate 和 WorkflowAssociation。
在该表中可以看出,<CustomAction> 元素在所有范围内均可用:Web(网站)、Site(网站集)、WebApplication 和 Farm(服务器场)。它是既不设置、也不取消设置的声明性元素,这意味着它直接从功能 XML 定义缓存到内存中,而在功能激活期间不会发生任何设置逻辑。因此,在激活功能并导航到包含自定义操作的页面后,将从缓存加载自定义操作,然后将其显示在该页面上。Field 元素仅在网站集范围内有效。它在激活时设置(创建网站栏)并在停用时取消设置(删除网站栏)。<ListInstance> 元素在 Web 和网站集范围内有效。它在激活时设置(创建列表实例),但在停用时不取消设置(不删除列表实例)。
备注
在功能激活期间设置在 <ElementManifests> 节指定的声明性元素,但是在功能升级时会忽略这些元素。因此,在升级中添加声明性元素的方法是将它们放置在 <ApplyElementManifests> 节。调用升级之前,必须在命令行中运行 iisreset 以刷新缓存,否则必须使用解决方案部署升级。