Entwicklungsrichtlinien für SharePoint Foundation-Cmdlets
Letzte Änderung: Mittwoch, 24. März 2010
Gilt für: SharePoint Foundation 2010
Wenn Sie Windows PowerShell-Cmdlets für SharePoint schreiben (benutzerdefinierte Cmdlets, die von der SPCmdlet-Basisklasse abgeleitet werden), müssen Sie sich an die SharePoint-spezifischen Entwurfsrichtlinienhalten. Dadurch stellen Sie sicher, dass die Cmdlets mit den Cmdlets in der SharePoint-Cmdlet-Bibliothek vollständig kompatibel sind, die in der SharePoint-Verwaltungsshell verfügbar gemacht werden. Außerdem werden in SharePoint Foundation enbenfalls Entwurfsmuster empfohlen, mit denen die vollständige Interoperabilität mit der SharePoint-Bereitstellung sichergestellt wird.
Methodik für das Erstellen von SharePoint-Cmdlets
Führen Sie beim Entwerfen SharePoint-spezifischer Cmdlets immer die folgenden Aufgaben aus:
Definieren Sie Cmdlet-Substantive.
Definieren Sie die Eigenschaften von Cmdlet-Substantiven.
Definieren Sie Cmdlet-Verben und -Parameter.
Definieren Sie Cmdlet-Fehler, den Fortschritt und die Pipeline.
Wenn Sie diesen Prozess einhalten, ergibt sich eine umfassende Definition des Cmdlet-Satzes für die Komponente oder das Feature, die bzw. das Sie entwickeln.
Definieren von Cmdlet-Substantiven
Achten Sie beim Definieren eines Cmdlet-Substantivs darauf, dass daraus klar hervorgeht, was mit dem Feature verwaltet werden soll. Stellen Sie sich die Substantive als Elemente vor, die von einem Systemadministrator verwaltet werden. Dabei kann es sich um SharePoint-Objekte wie beispielsweise die Objekte SPSite oder SPWeb handeln, oder um installierte Features wie beispielsweise SPFeature-Objekte, Formularvorlagen oder Webparts.
Allgemein ist es besser, mehr Substantive mit weniger Eigenschaften zu haben als wenige Substantive mit vielen Eigenschaften. Mehr als 15 Eigenschaften für ein Substantiv sind eindeutig zu viel.
Identifizieren Sie die nicht permanenten Laufzeitstatusinformationen, die Sie für Systemadministratoren verfügbar machen möchten. Identifizieren Sie außerdem Statusinformationen, die möglicherweise nicht permanent sind, aber dennoch an Systemadministratoren zurückgegeben werden müssen (beispielsweise der Ausführungsstatus eines Diensts).
Bewerten Sie, ob ein neu definiertes Substantiv in zwei oder mehr verschiedene Substantive aufgeteilt werden sollte. Erstellen Sie separate Substantive für semantisch unterschiedliche Elemente. Verwenden Sie Feature- oder Komponentenangaben, um zu identifizieren, ob ein Substantiv für mehrere Konzepte oder Features gilt.
Wenn ein Substantiv für mehrere (physikalische oder logische) Datenquellen gilt, teilen Sie das Substantiv an den Datenquellengrenzen auf. Identifizieren Sie eine logisch unabhängige Teilmenge der Eigenschaften, die nur in einer einzigen Datenbank oder einem einzigen SharePoint-Objekt gespeichert wird. In den meisten Fällen sollte diese Teilmenge als separates Substantiv verwendet werden. Dies gilt jedoch nur, wenn die sich ergebenden Substantive logisch unabhängig sind und eindeutig als unterschiedliche Entitäten verstanden werden (das heißt leicht getrennt werden können), ohne die Systemadministratoren zu verwirren.
Führen Sie die Substantive aller permanenten Datenquellenobjekte, die von mehr als einem Substantiv verwendet werden, in einem einzigen Substantiv zusammen. Führen Sie außerdem Substantive zusammen, die sich in erster Linie durch die unterschiedliche Lebensdauer unterscheiden, da die Erstellung und Löschung dieser Substantive getrennt verwaltet werden kann.
Definieren der Eigenschaften von Cmdlet-Substantiven
Definieren Sie eine Identity-Eigenschaft. Alle Substantive müssen über eine Identity-Eigenschaft verfügen, deren Wert eindeutig und unveränderlich ist, beispielsweise eine GUID.
Erstellen Sie eine Pipebindung für das Substantiv. In der Pipebindung sollten alle Eigenschaften kombiniert werden, durch die das Objekt eindeutig identifiziert werden kann.
Definieren Sie den vollständigen Satz der öffentlichen Eigenschaften des Substantivs. Behandeln Sie die Substantivdefinition wie eine öffentliche API. Alle zugehörigen öffentlichen Eigenschaften werden auf der Befehlszeile verfügbar gemacht, wenn eine Instanz des Substantivs zurückgegeben wird.
Definieren Sie für jede Eigenschaft einen Datentyp. Eigenschaften sollten stark typisiert sein, damit der Formatüberprüfungscode dem Eigenschaftentyp anstatt dem Substantiv angefügt werden kann. Beispielsweise sollten Sie für eine Eigenschaft, die eine E-Mail-Adresse darstellt, nicht den Typ String, sondern den Typ EmailAddress verwenden.
Identifizieren Sie atypisch große Eigenschaften. Stellen Sie sicher, dass ungewöhnlich große Eigenschaften (größer als 10 KB) in mindestens zwei Eigenschaften aufgeteilt werden.
Identifizieren Sie Auflistungen von Eigenschaften mit zahlreichen Elementen (beispielsweise eine Auflistung mit mehr als 100 Elementen). Entfernen Sie solche umfangreichen Eigenschaftenauflistungen, und teilen Sie die Elemente in separate Substantive auf. Definieren Sie dann die Verben New, Remove, Get und Set für die neuen Substantive.
Stellen Sie sich beispielsweise ein Szenario vor, in dem Users eine Eigenschaft eines SPWeb-Objekts ist, das eine große Anzahl von Elementen haben kann. Vermeiden Sie Probleme, indem Sie ein separates Substantiv mit dem Namen SPUser erstellen, das ein Element in der Liste darstellt, und dann die zugeordneten Verben New, Remove, Get und Set hinzufügen.
Definieren von Cmdlet-Verben und -Parametern
Bestimmten Sie, welche der Basisverben (Get, Set, New, Remove) für das Substantiv gelten. Systemadministratoren müssen mindestens in der Lage sein, Einstellungen abzurufen und zu ändern (oder Set zu verwenden). Darüber hinaus müssen Administratoren möglicherweise auch neue Instanzen erstellen (New) und vorhandene Instanzen löschen (Remove).
Definieren Sie das Verhalten des Get-Cmdlets.
Mit dem Get-Verb müssen alle Instanzen abgerufen werden, wenn keine Parameter angegeben sind, und dazu müssen die Instanzen in die Windows PowerShell-Pipeline geschrieben werden. Jeder Vorgang, mit dem theoretisch ein sehr umfangreicher Ergebnissatz zurückgegeben werden kann, sollte jedoch einen Limit-Parameter enthalten, für den ein Standardlimit angegeben ist. Natürlich müssen Sie, wenn Sie einen Ergebnissatz auf diese Weise begrenzen, die Benutzer darauf hinweisen, dass möglicherweise zusätzliche Ergebnisse aus dem begrenzten Ergebnissatz ausgeschlossen wurden.
Das Get-Verb muss einen Identity-Parameter aufweisen. Wenn dieser Parameter angegeben ist, darf durch das entsprechende Cmdlet nur die Instanz zurückgegeben werden, die dieser Identität zugeordnet ist. Wenn die angegebene Identität nicht eindeutig ist, sollten alle Instanzen zurückgegeben werden, die den angegebenen Identitätswert aufweisen.
Für das Get-Verb können zusätzliche optionale Filterparameter verwendet werden. Beispielsweise können Sie für das Get-SPSite-Cmdlet einen ContentDatabase-Parameter verwenden, mit dem der Ergebnissatz auf Websitesammlungen beschränkt wird, die sich in einer angegebenen Inhaltsdatenbank befinden. Außerdem muss für das Get-Verb ein Server-Parameter verwendet werden, wenn durch das Cmdlet lokale (d. h. computerspezifische) Konfigurationsinformationen zurückgegeben werden.
Definieren Sie das Verhalten des Set-Cmdlets.
Das Set-Verb muss einen Identity-Parameter aufweisen, mit dem die zu ändernde Instanz identifiziert wird. Der Parameter muss mit einer Identität (beispielsweise einer GUID) oder einem Namen verwendet werden können. Wenn ein Name angegeben ist, der mit mehr als einer Instanz übereinstimmt, muss durch das Cmdlet ein Fehler zurückgegeben werden.
Der Identity-Parameter des Set-Cmdlets muss mit Pipelineeingaben verwendet werden können.
Durch das Set-Verb müssen alle schreibbaren Eigenschaften des mithilfe des entsprechenden Get-Cmdlets empfangenen Substantivs verfügbar gemacht werden, mit Ausnahme von Eigenschaften, deren Festlegung negative Auswirkungen hat.
Das Set-Verb muss einen optionalen Instance-Parameter aufweisen, der eine vollständige Instanz dieses Substantivtyps darstellt. Der Instance-Parameter muss mit Pipelineeingaben (nach Werten) verwendet werden können.
Definieren Sie das Verhalten des New-Cmdlets.
Für das New-Verb muss eine begrenzte Teilmenge der schreibbaren Eigenschaften des Substantivs als Parameter verwendet werden können. Die übrigen Eigenschaften sollten auf Standardwerte festgelegt werden. Außerdem muss durch das New-Cmdlet das neu erstellte Instanzobjekt an die Pipeline zurückgegeben werden, damit durch weitere Cmdlets in der Pipeline Aktionen für die neue Instanz ausgeführt werden können.
Definieren Sie das Verhalten des Remove-Cmdlets.
Das Remove-Cmdlet muss einen Identity-Parameter aufweisen, für den ein Identitätswert oder ein Name verwendet werden kann. Wenn ein Name angegeben ist, der mit mehr als einer Instanz übereinstimmt, muss durch das Cmdlet ein Fehler zurückgegeben werden.
Der Identity-Parameter muss mit Pipelineeingaben verwendet werden können. Außerdem müssen von allen destruktiven Vorgängen die Parameter Confirm und WhaIf unterstützt werden. Dies erfordert wenig Aufwand, da in Windows PowerShell und den Basisklassen von SharePoint Foundation 2010 Methoden für die Unterstützung dieser Parameter bereitgestellt werden.
Identifizieren und definieren Sie zusätzliche Verben für das Substantiv.
Für ein SPContentDatabase-Substantiv beispielsweise wird möglicherweise ein Mount-Verb benötigt, um die Bereitstellung der angegebenen Datenbank zu unterstützen. Verwenden Sie sorgfältig getestete Verwaltungsszenarien und Anwendungsfälle, um die Auswahl geeigneter Verben zu unterstützen.
Denken Sie daran, dass alle zusätzlichen Cmdlets einen Identity-Parameter aufweisen müssen, für den Pipelineeingaben verwendet werden können. Für den Identity-Parameter muss die Identität (PipeBind) des Objekts verwendet werden können. Außerdem müssen von allen destruktiven Vorgängen die Parameter Confirm und WhaIf unterstützt werden.
Identifizieren Sie Eigenschaften mit potenziellen negativen Nebenwirkungen.
Für Eigenschaften mit potenziellen negativen Nebenwirkungen sind möglicherweise zusätzliche Vorgänge erforderlich, um die negativen Auswirkungen zu entschärfen. Diese zusätzlichen entschärfenden Cmdlets müssen einen Identity-Parameter aufweisen, für den Pipelineeingaben verwendet werden können.
Führen Sie für jedes definierte Cmdlet die folgenden Aufgaben aus:
(a) Identifizieren Sie die Liste der Voraussetzungen für das Cmdlet. Wenn ein Cmdlet beispielsweise nur bei einem bestimmten Systemstatus ausgeführt werden kann, muss durch das Cmdlet vor der Ausführung überprüft werden, ob alle Statusvoraussetzungen erfüllt sind.
(b) Identifizieren Sie die Liste der Vorgänge. Geben Sie die vollständige Liste der Vorgänge an, die durch das Cmdlet ausgeführt werden können. Diese Vorgänge müssen durch das Cmdlet ausgeführt und anschließend überprüft werden. Die Vorgangsliste umfasst einen Strukturplan der Funktionen des Cmdlets.
Definieren der Cmdlet-Fehler, des Fortschritts und der Pipeline
Identifizieren Sie alle Fehlerbedingungen und Verhaltensweisen bei Vorliegen eines Fehlerzustands. Das heißt, listen Sie alle Bedingungen auf, unter denen ein Fehler bei einem Cmdlet auftreten kann. Beschreiben Sie dann das für die einzelnen Bedingungen erwartete Verhalten. Für die Cmdlets muss eine einfache Fehlerverwaltung bereitgestellt werden.
Bei Auftreten eines Fehlers müssen teilweise Änderungen von den Cmdlets bereinigt werden, und es muss eine aussagekräftige (und gegebenenfalls lokalisierte) Fehlermeldung zurückgegeben werden. Außerdem muss durch die Cmdlets ermittelt und offen gelegt werden, auf welche Weise ein Systemadministrator bei einer Fehlerbedingung eine Wiederherstellung ausführen kann.
Differenzieren Sie zwischen Fehlern mit Abbruch und Fehlern ohne Abbruch.
Identifizieren Sie lange ausgeführte Vorgänge. Wenn das Abschließen eines Vorgangs durch ein Cmdlet voraussichtlich länger als durchschnittlich etwa zwanzig Sekunden dauert, müssen Fortschrittsinformationen bereitgestellt werden, damit nicht der Eindruck entsteht, dass der Vorgang angehalten wurde.
Stellen Sie sicher, dass die Rückgabeobjekte von Cmdlets direkt in die Pipeline geschrieben werden. Vermeiden Sie das Puffern abgerufener Objekte in einem internen Array. Wenn in die Pipeline geschrieben wird, können von den nachgelagerten Cmdlets Aktionen für vorangegangene Objekte in der Pipeline ohne Verzögerung ausgeführt werden.
Gruppieren Sie ähnliche Parameter. Begrenzen Sie Cmdlets auf 16 Parameter (die Parameter Identity und Name nicht eingerechnet). In Fällen, in denen Objektmethoden selten aufgerufen werden und eine Objektmodellmethode vorhanden ist, werden keine Cmdlet-Parameter benötigt. In Fällen, in denen zahlreiche Parameter gruppiert werden können, schreiben Sie einen einzelnen Parameter, für den das Gruppenobjekt verwendet werden kann.