功能升级对象模型

上次修改时间： 2010年7月9日

适用范围： SharePoint Foundation 2010

本文内容
FeatureUpgrading 事件
Version 属性
QueryFeatures 方法
Upgrade 方法

为了提供功能升级能力，Microsoft SharePoint Foundation 对象模型中已经添加了新的类型和成员。这些类型和成员包括：

• FeatureUpgrading 事件

• Version 属性

• QueryFeatures 方法

• Upgrade 方法

FeatureUpgrading 事件

功能接收器 (SPFeatureReceiver) 现在可用于处理 FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) 事件。您可以实现自己的自定义功能接收器来升级功能实例。

FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) 参数包含当前执行的上下文的属性、将执行的自定义升级操作的名称以及自定义升级操作参数的词典。

有关说明如何使用 FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>) 方法的示例，请参阅如何：使用升级代码激活具有依赖项的功能。

Version 属性

现有的 SPFeatureDefinition 类已具有一个 Version 属性，而 SharePoint Foundation 中的 SPFeature 类还提供一个新的 Version。但是，在 Feature.xml 文件中指定的当前功能版本是在 SPFeatureDefinition 类中定义的版本。Version 是唯一在指定作用域中与某个功能实例相关联的版本类，而该作用域与功能定义版本可能并不匹配。

如果与某个特定作用域中的对象（例如 SPWebApplication 或 SPSite 对象）关联的一个或多个功能的版本号比与该功能实例关联的 Feature.xml 文件中指定的版本号低，则确定该对象需要升级。

版本格式为 xxxx. xxxx. xxxx. xxxx，其中 x 是一个数字。如果 Feature.xml 文件未指定 Version 属性，则默认版本为"0.0.0.0"。

QueryFeatures 方法

新的 QueryFeatures 方法允许您通过使用一组筛选条件来查询不同作用域中的功能。SPWebService、SPWebApplication、SPContentDatabase 和 SPSite 类均提供一个 QueryFeatures 方法，其重载允许您指定不同的条件来确定返回哪个功能实例结果集。

• SPWebService -- 在服务器场中查找符合筛选条件的已激活的功能实例。

• SPWebApplication -- 查找符合指定筛选条件的 Web 应用程序、网站集和网站范围的功能。将针对 Web 应用程序对象中的所有内容数据库运行查询，并按照内容数据库对返回的集合进行排序。

• SPContentDatabase -- 在内容数据库中查找范围限定为网站集和网站并符合指定的筛选条件的功能。返回的集合相对于网站层次结构排序。例如，父网站的功能在子网站功能之前表示，层次结构为从上至下。

• SPSite -- 查找所有符合特定筛选条件的网站集和网站范围的功能。返回的集合按照网站层次结构排序。父网站的功能显示在子网站功能的前面，并且按照从上至下的方式安排层次结构。新的客户端对象模型中提供了此类的 QueryFeatures 方法的重载。

重载

为上面列出的每一个类提供了 QueryFeatures 方法的以下四个重载：

• 返回具有指定作用域的所有功能实例。可使用 needsUpgrade 参数返回需要升级的所有功能。

  public Microsoft.SharePoint.SPFeatureQueryResultCollection 
  QueryFeatures(Microsoft.SharePoint.SPFeatureScope scope, bool needsUpgrade)
  

• 返回具有指定功能 ID 的所有功能实例。可使用 needsUpgrade 参数返回需要升级的所有功能。

  public Microsoft.SharePoint.SPFeatureQueryResultCollection 
  QueryFeatures(System.Guid featureId, bool needsUpgrade)
  

• 返回具有指定功能 ID 和版本号的所有功能实例。

  public Microsoft.SharePoint.SPFeatureQueryResultCollection 
  QueryFeatures(System.Guid featureId, System.Version featureVersion)
  

• 返回具有指定功能 ID 的所有功能实例。

  public Microsoft.SharePoint.SPFeatureQueryResultCollection    
  QueryFeatures(System.Guid featureId)
  

SPFeatureQueryResultCollection 类用于枚举通过 QueryFeatures 操作返回的功能。

在升级期间，QueryFeatures 方法在它发现某个实例版本号低于当前 Feature.xml 定义版本号时，确定某个功能实例是否过期。根据 Feature.xml 文件中的 UpgradeActions 指令，将为每一个需要升级的功能实例调用升级。在成功升级某个功能实例之后，其版本号将会更新以匹配 Feature.xml 文件定义版本号。

Upgrade 方法

SPFeature 类现在提供一个 Upgrade(Boolean) 方法来为所有作用域中的某个功能实例执行升级：Farm、WebApplication、Site 和 Web。

在对一个从属功能实例调用 QueryFeatures 方法时，该方法首先升级相关层次结构中最高级别的功能实例，然后升级依赖该功能的所有功能实例。这种按层次结构升级的过程可确保所有从属功能实例与其所依赖的功能实例保持同步。

重要信息
不要从某个功能升级事件接收器内部调用 Upgrade(Boolean) 方法。例如，不要对可通过以下类似代码获取的功能调用此方法： SPFeatureQueryResultCollection queryResults = myWebService.QueryFeatures(myScope, true); IEnumerator<SPFeature> featureEnumerator = queryResults.GetEnumerator();