Schlüsselkonzepte für das Schreiben von Cmdlets für die SharePoint-Verwaltungsshell

Letzte Änderung: Donnerstag, 1. Oktober 2009

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
Cmdlet-Parameter
Pipelines und Weiterleitung
PipeBind-Objekte

Beim Schreiben von Cmdlets für Windows PowerShell spielen verschiedene Schlüsselkonzepte eine elementare Rolle. Im folgenden Artikel werden ohne Anspruch auf Vollständigkeit einige der wichtigen Konzepte genannt, die die Implementierung von Windows PowerShell für SharePoint unterstützen.

Cmdlet-Parameter

Obwohl Benutzer Parameterwerte als Zeichenfolgen eingeben, wird in Windows PowerShell versucht, diese Zeichenfolgenwerte basierend auf der Parameterdefinition in den richtigen Typ zu konvertieren. Daher müssen Sie Cmdlets so schreiben, dass die Gültigkeit des Datentyps der dem Cmdlet übergebenen Parameterwerte überprüft werden kann.

Vermeiden Sie das Übergeben von Parametern vom Typ Zeichenfolge oder Ganzzahl, wenn nicht alle Werte dieses Typs für die Parameter gültig sind. Definieren Sie stattdessen eine Klasse, mit der der Bereich und das Format der Parameter weiter eingeschränkt werden. Überprüfen Sie außerdem Parameter mithilfe der Parse(String)-Methode des Parametertyps. Von Windows PowerShell wird die Verwendung der Parse()-Methode zum Konvertieren eines Zeichenfolgentyps in andere Datentypen unterstützt.

Pipelines und Weiterleitung

Zu den wichtigsten Verbesserungen in Windows PowerShell, die über die Funktionen von Cmd.exe hinausgehen, gehört die systemeigene Möglichkeit, in Windows PowerShell eine Reihe einfacher Cmdlets in einer Pipeline, das heißt einer Reihe oder Sequenz von Befehlen, zu kombinieren. Mithilfe der Pipeline können Ausgabeobjekte eines Befehls als Eingabeobjekte für nachfolgende Befehle übergeben (oder weitergeleitet) werden. Mithilfe von Befehlspipelines können Cmdlet-Entwickler komplexe, flexible Befehlspipelines erstellen, deren Ausgabeobjekte gespeichert und wiederverwendet werden können.

Der Weiterleitungsprozess basiert auf dem Cmdlet-Verhalten, bei dem Ausgabeobjekte in eine Objektpipeline geschrieben werden, die von Windows PowerShell gesteuert wird. Auf diese Weise kann von Windows PowerShell versucht werden, das Objekt in der Pipeline den Parametern des nachfolgenden Cmdlets zuzuordnen.

Damit die Weiterleitung verwendet werden kann, muss eine explizite Entsprechung zwischen der Ausgabe des vorhergehenden Cmdlets und der Eingabe der folgenden Cmdlets bestehen. Diese Entsprechung kann auf Objektebene bestehen, sodass das vorhergehende Objekt in der Pipeline einem Parameter im nachfolgenden Cmdlet entspricht. (Dies wird als Weiterleitung nach Werten bezeichnet.) Alternativ kann die Entsprechung auf Eigenschaftsebene bestehen, sodass die Eigenschaften des vorhergehenden Objekts in der Pipeline den Parametern des nachfolgenden Cmdlets entsprechen.

Weiterleitung nach Werten

Bei der Weiterleitung nach Werten wird von einem nachgelagerten Cmdlet ein vollständiges Objekt aus der Pipeline verwendet, sofern das Objekt den richtigen Typ aufweist. Für die Weiterleitung nach Werten werden in der Regel Set-Cmdlets verwendet, bei denen durch das Übergeben eines vollständigen Objekts ein Lesevorgang von einer Datenquelle gespeichert wird, oder auch New-Cmdlets mit Unterstützung für Klonen. Die Weiterleitung nach Werten wird auch in Fällen verwendet, in denen das vom vorgelagerten Cmdlet ausgegebene Objekt vom nachgelagerten Cmdlet nicht erneut gelesen werden kann.

PipeBind-Objekte

PipeBind-Objekte sind spezielle Objekte, die nur in Windows PowerShell für SharePoint verwendet werden und eine zweite Ebene mit spezialisierten, für SharePoint Foundation optimierten Parametersätzen bereitstellen.

Wenn Sie SharePoint Foundation 2010-Objekte als Cmdlet-Parameter verwenden, sollten Sie anstelle des SharePoint-Objekts das entsprechende PipeBind-Objekt verwenden. Dies ist unerlässlich, da der Benutzer des Cmdlets dann den Wert des Parameters richtig angeben kann. Das PipeBind-Objekt stellt tatsächlich eine Ebene dar, die sich zwischen der Benutzereingabe für einen Parameter und dem Parameterobjekt selbst befindet.

Beispielsweise kann für ein Cmdlet, für das ein SPSite-Parameter verwendet werden kann, entweder das SPSite-Objekt selbst oder der GUID-Bezeichner für die jeweilige Websitesammlung oder anderenfalls die URL der Websitesammlung verwendet werden. Mit dem SPSitePipeBind-Objekt wird sichergestellt, dass ungeachtet der durch die Windows PowerShell-Laufzeit angezeigten Darstellung das Cmdlet selbst mit dem eigentlichen SPSite-Objekt angezeigt wird.

Hinweis
PipeBind-Klassen sollten nicht an bestimmte Cmdlets gebunden, sondern für alle Cmdlets verwendet werden. Stellen Sie beim Schreiben eines PipeBind-Cmdlets sicher, dass keine für den Cmdlet-Implementierer spezifischen Anforderungen gelten.

Implementieren eines PipeBind-Objekts

Beim Implementieren eines PipeBind-Objekts müssen Sie von der SPCmdletPipeBind<TCmdletObject>-Basisklasse ableiten. Zum Implementieren dieser Klasse führen Sie die folgenden Schritte aus:

1. Implementieren Sie den Klassenkonstruktor.

2. Setzen Sie die Read()-Methode des Objekts außer Kraft.

Die PipeBind-Klasse sollte über mindestens einen Konstruktor verfügen, mehrere Konstruktoren sind ebenfalls möglich. Wenn von Windows PowerShell versucht wird, Parameter zu binden, wird der Satz der öffentlichen Konstruktoren nach einem angegebenen Parameter durchlaufen, und es wird versucht, die Parametereingabe einem PipeBind-Konstruktor zuzuordnen. Das heißt, dass für jeden möglichen Eingabetyp, der einen Parameter darstellt, ein entsprechender Konstruktor vorhanden sein muss.

Mit der Read()-Methode des SPCmdletPipeBind<TCmdletObject>-Objekts wird der Objekttyp zurückgegeben, der im SharePoint Foundation-Objektmodell definiert ist: public virtual TCmdletObject Read().

Die Read()-Methode muss für die einzelnen PipeBind-Objektimplementierungen außer Kraft gesetzt werden, um sicherzustellen, dass das Objekt des Objektmodells richtig abgerufen wird. Sie können nach Bedarf zusätzliche Außerkraftsetzungen der Read()-Methode erstellen, um die erforderlichen Parameter bereitzustellen.

Identität und Unteilbarkeit von Cmdlets

Cmdlets müssen über einen Identity-Parameter verfügen, mit dem das Objekt angegeben wird, für das Aktionen ausgeführt werden sollen. Sie müssen beim Schreiben von Cmdlets einen eindeutigen Bezeichner als Wert für den Identity-Parameter angeben. Beachten Sie jedoch, dass neue Cmdlets anfangs keinen Bezeichner haben; ein Bezeichner kann erst nach der Instanziierung des Objekts vorhanden sein.

Bei der Cmdlet-Ausführung sollte Unteilbarkeit simuliert werden. Das heißt, das Cmdlet sollte entweder erfolgreich ausgeführt werden und das System in einen geänderten Zustand versetzen, oder es sollten ordnungsgemäß Fehlermeldungen angezeigt werden, und das System sollte wieder in den Zustand vor der Ausführung versetzt werden. Mit anderen Worten, für Cmdlets muss eine Methode bereitgestellt werden, mit der der Systemzustand im Fall eines Fehlers wiederhergestellt werden kann.