Featureupgrade-Objektmodell

Artikel
09/24/2014

Letzte Änderung: Freitag, 9. Juli 2010

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
FeatureUpgrading-Ereignis
Version-Eigenschaft
QueryFeatures-Methode
Upgrade-Methode

Für die Funktion des Featureupgrades wurden dem Microsoft SharePoint Foundation-Objektmodell neue Typen und Member hinzugefügt. Dazu gehören folgende:

FeatureUpgrading-Ereignis
Version-Eigenschaft
QueryFeatures-Methoden
Upgrade-Methode

FeatureUpgrading-Ereignis

Zur Verarbeitung von FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>)-Ereignissen können nun Featureempfänger (SPFeatureReceiver) verwendet werden. Sie können einen eigenen benutzerdefinierten Featureempfänger für das Upgrade von Featureinstanzen implementieren.

Die FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>)-Parameter enthalten Eigenschaften des aktuellen Ausführungskontexts, den Namen der auszuführenden benutzerdefinierten Upgradeaktion und ein Wörterbuch der Parameter der benutzerdefinierten Upgradeaktion.

Ein Beispiel für die Verwendung der FeatureUpgrading(SPFeatureReceiverProperties, String, IDictionary<String, String>)-Methode finden Sie unter Vorgehensweise: Aktivieren eines Features mit Abhängigkeiten mithilfe von Upgradecode.

Version-Eigenschaft

Die vorhandene SPFeatureDefinition-Klasse verfügt bereits über eine Version-Eigenschaft, und die SPFeature-Klasse in SharePoint Foundation bietet ebenfalls eine neue Version-Eigenschaft. Die in der Datei Feature.xml angegebene aktuelle Featureversion entspricht jedoch der Version, die in der SPFeatureDefinition-Klasse definiert ist. Version ist eine eindeutige Versionsklasse, die einer Featureinstanz in einem angegebenen Bereich zugeordnet ist. Diese stimmt unter Umständen nicht mit der Version der Featuredefinition überein.

Ein Objekt in einem bestimmten Bereich, wie z. B. ein SPWebApplication- oder SPSite-Objekt, muss aktualisiert werden, wenn mindestens eines der ihm zugeordneten Features eine niedrigere Versionsnummer aufweist als in der Feature.xml-Datei angegeben ist, die dieser Featureinstanz zugeordnet ist.

Die Version hat das Format xxxx. xxxx. xxxx. xxxx, wobei x eine einzelne Ziffer darstellt. Ist in der Datei Feature.xml kein Version-Attribut angegeben, wird die Standardversion 0.0.0.0 angenommen.

Hinweis
In SharePoint Foundation sind keine "kurzen" Versionsnummern mit weniger als vier Zahlen für eine Version (wie z. B. "1.0") zulässig. In diesem Fall wird eine Ausnahme ausgelöst.

QueryFeatures-Methode

Mit den neuen QueryFeatures-Methoden können Sie Features in verschiedenen Bereichen mithilfe eines Satzes von Filterkriterien abfragen. Jede der Klassen SPWebService, SPWebApplication, SPContentDatabase und SPSite bietet eine QueryFeatures-Methode, durch deren Überladungen Sie unterschiedliche Kriterien angeben können, um zu bestimmen, welches Resultset von Featureinstanzen zurückgegeben werden soll.

SPWebService – Sucht aktivierte Featureinstanzen in der Serverfarm, die den Filterkriterien entsprechen.
SPWebApplication – Sucht eine Webanwendung, eine Websitesammlung und auf den Websitebereich beschränkte Features, die den angegebenen Filterkriterien entsprechen. Die Abfrage wird für alle Inhaltsdatenbanken im Webanwendungsobjekt ausgeführt, und die zurückgegebene Auflistung wird nach Inhaltsdatenbank sortiert.
SPContentDatabase – Sucht Features in der Inhaltsdatenbank, die auf den Bereich der Websitesammlung und der Website beschränkt sind und die den angegebenen Filterkriterien entsprechen. Die zurückgegebene Auflistung wird entsprechend der Websitehierarchie sortiert. Beispielsweise werden Features übergeordneter Websites vor Features untergeordneter Websites dargestellt. Die Hierarchie wird von oben nach unten durchlaufen.
SPSite – Sucht alle auf die Websitesammlung und die Website beschränkten Features, die den angegebenen Filterkriterien entsprechen. Die zurückgegebene Auflistung wird entsprechend der Websitehierarchie sortiert. Beispielsweise werden Features übergeordneter Websites vor Features untergeordneter Websites dargestellt. Die Hierarchie wird von oben nach unten durchlaufen. Überladungen der QueryFeatures-Methode für diese Klasse stehen in den neuen clientseitigen Objektmodellen zur Verfügung.

Überladungen

Für jede der oben aufgeführten Klassen werden die folgenden vier Überladungen der QueryFeatures-Methode bereitgestellt:

Rückgabe aller Featureinstanzen mit dem angegebenen Bereich. Mithilfe des needsUpgrade-Parameters können Sie alle Features zurückgeben, die ein Upgrade benötigen.
```
public Microsoft.SharePoint.SPFeatureQueryResultCollection 
QueryFeatures(Microsoft.SharePoint.SPFeatureScope scope, bool needsUpgrade)
```
Rückgabe aller Featureinstanzen mit der angegebenen Feature-ID. Mithilfe des needsUpgrade-Parameters können Sie alle Features zurückgeben, die ein Upgrade benötigen.
```
public Microsoft.SharePoint.SPFeatureQueryResultCollection 
QueryFeatures(System.Guid featureId, bool needsUpgrade)
```

Rückgabe aller Featureinstanzen mit der angegebenen Feature-ID und Versionsnummer.

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

Rückgabe aller Featureinstanzen mit der angegebenen Feature-ID.

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

Die SPFeatureQueryResultCollection-Klasse dient zum Aufzählen der Features, die durch einen QueryFeatures-Vorgang zurückgegeben werden.

Beim Upgrade wird eine Featureinstanz von der QueryFeatures-Methode als veraltet erkannt, wenn eine Instanzversionsnummer gefunden wird, die niedriger ist als die aktuelle Versionsnummer in der Feature.xml-Definition. Basierend auf den UpgradeActions-Direktiven in der Datei Feature.xml wird das Upgrade für jede Featureinstanz aufgerufen, für die es erforderlich ist. Nach dem erfolgreichen Upgrade einer Featureinstanz wird ihre Versionsnummer auf die Versionsnummer der Definition in der Datei Feature.xml aktualisiert.

Upgrade-Methode

Die SPFeature-Klasse bietet nun eine Upgrade(Boolean)-Methode zur Ausführung eines Upgrades für eine Featureinstanz in allen Bereichen: Farm, WebApplication, Site und Web.

Wenn die QueryFeatures-Methode für eine abhängige Featureinstanz aufgerufen wird, wird das Upgrade zunächst für die Featureinstanz der obersten Ebene in der betreffenden Hierarchie ausgeführt und dann für alle Featureinstanzen, die von diesem Feature abhängen. Durch diesen hierarchischen Upgradeprozess wird sichergestellt, dass alle abhängigen Featureinstanzen mit der Featureinstanz, von der sie abhängen, synchronisiert bleiben.

Wichtig
Rufen Sie die Upgrade(Boolean)-Methode nicht aus einem Featureempfänger für das Featureupgrade auf. Rufen Sie die Methode z. B. nicht für die Features auf, die über den folgenden Code abgerufen werden können: SPFeatureQueryResultCollection queryResults = myWebService.QueryFeatures(myScope, true); IEnumerator<SPFeature> featureEnumerator = queryResults.GetEnumerator();

Rufen Sie die Upgrade(Boolean)-Methode nicht aus einem Featureempfänger für das Featureupgrade auf. Rufen Sie die Methode z. B. nicht für die Features auf, die über den folgenden Code abgerufen werden können:

SPFeatureQueryResultCollection queryResults = myWebService.QueryFeatures(myScope, true);

IEnumerator<SPFeature> featureEnumerator = queryResults.GetEnumerator();

Freigeben über