Freigeben über

Erforderliche Entwicklungsrichtlinien

Die folgenden Richtlinien müssen befolgt werden, wenn Sie Ihre Cmdlets schreiben. Sie sind in Richtlinien für das Entwerfen von Cmdlets und Richtlinien zum Schreiben des Cmdlet-Codes unterteilt. Wenn Sie diese Richtlinien nicht befolgen, können Ihre Cmdlets fehlschlagen, und Ihre Benutzer haben möglicherweise eine schlechte Erfahrung, wenn sie Ihre Cmdlets verwenden.

In diesem Thema

Entwurfsrichtlinien

Coderichtlinien

Entwurfsrichtlinien

Die folgenden Richtlinien müssen beim Entwerfen von Cmdlets befolgt werden, um eine konsistente Benutzererfahrung zwischen der Verwendung Ihrer Cmdlets und anderen Cmdlets sicherzustellen. Wenn Sie eine Designrichtlinie finden, die für Ihre Situation gilt, sollten Sie sich die Coderichtlinien für ähnliche Richtlinien ansehen.

Nur genehmigte Verben verwenden (RD01)

Das im Cmdlet-Attribut angegebene Verb muss aus der erkannten Gruppe von Verben stammen, die von Windows PowerShell bereitgestellt werden. Es darf nicht eines der verbotenen Synonyme sein. Verwenden Sie die konstanten Zeichenfolgen, die durch die folgenden Enumerationen definiert sind, um Cmdlet-Verben anzugeben:

Weitere Informationen zu den genehmigten Verbnamen finden Sie unter Cmdlet Verbs.

Benutzer benötigen eine Reihe von auffindbaren und erwarteten Cmdlet-Namen. Verwenden Sie das entsprechende Verb, damit der Benutzer eine schnelle Bewertung der Funktionsweise eines Cmdlets vornehmen und die Funktionen des Systems leicht ermitteln kann. Beispielsweise ruft der folgende Befehlszeilenbefehl eine Liste aller Befehle auf dem System ab, deren Namen mit "Start" beginnen: Get-Command Start-*. Verwenden Sie die Substantive in Ihren Cmdlets, um Ihre Cmdlets von anderen Cmdlets zu unterscheiden. Das Substantiv gibt die Ressource an, für die der Vorgang ausgeführt wird. Der Vorgang selbst wird durch das Verb dargestellt.

Cmdlet-Namen: Zeichen, die nicht verwendet werden können (RD02)

Verwenden Sie beim Benennen von Cmdlets keines der folgenden Sonderzeichen.

Charakter Name
# Nummernzeichen
, Komma
() Klammern
{} Hosenträger
[] Klammern
& Kaufmännisches Und-Zeichen
- Bindestrich Hinweis: Der Bindestrich kann verwendet werden, um das Verb vom Substantiv zu trennen, kann aber nicht innerhalb des Substantivs oder innerhalb des Verbs verwendet werden.
/ Schrägstrich
\ umgekehrter Schrägstrich
$ Dollarzeichen
^ caret
; Semikolon
: Doppelpunkt
" Doppeltes Anführungszeichen
' Einfaches Anführungszeichen
<> Eckige Klammern
| senkrechter Strich
? Fragezeichen
@ At-Zeichen
` Zurück-Teilstrich (gravierer Akzent)
* Sternchen
% Prozentzeichen
+ Pluszeichen
= Gleichheitszeichen
~ Tilde

Parameternamen, die nicht verwendet werden können (RD03)

Windows PowerShell bietet einen allgemeinen Satz von Parametern für alle Cmdlets sowie zusätzliche Parameter, die in bestimmten Situationen hinzugefügt werden. Beim Entwerfen eigener Cmdlets können Sie die folgenden Namen nicht verwenden: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction und Verbose. Weitere Informationen zu diesen Parametern finden Sie unter Common Parameter Names.

Supportbestätigungsanfragen (RD04)

Für Cmdlets, die einen Vorgang ausführen, der das System ändert, sollten sie die System.Management.Automation.Cmdlet.ShouldProcess* Methode aufrufen, um eine Bestätigung anzufordern, und in sonder fällen die System.Management.Automation.Cmdlet.ShouldContinue* Methode aufrufen. (Die System.Management.Automation.Cmdlet.ShouldContinue* Methode sollte erst aufgerufen werden, nachdem die System.Management.Automation.Cmdlet.ShouldProcess* Methode aufgerufen wird.)

Um diese Aufrufe auszuführen, muss das Cmdlet angeben, dass es Bestätigungsanforderungen unterstützt, indem das schlüsselwort SupportsShouldProcess des Cmdlet-Attributs festgelegt wird. Weitere Informationen zum Festlegen dieses Attributs finden Sie unter Cmdlet-Attributdeklaration.

Hinweis

Wenn das Cmdlet-Attribut der Cmdlet-Klasse angibt, dass das Cmdlet Aufrufe an die System.Management.Automation.Cmdlet.ShouldProcess* Methode unterstützt und das Cmdlet den Aufruf des System.Management.Automation.Cmdlet.ShouldProcess*-Methode fehlschlägt, kann der Benutzer das System unerwartet ändern.

Verwenden Sie die System.Management.Automation.Cmdlet.ShouldProcess* Methode für jede Systemänderung. Eine Benutzereinstellung und der WhatIf Parameter steuern die System.Management.Automation.Cmdlet.ShouldProcess*-Methode. Im Gegensatz dazu führt der System.Management.Automation.Cmdlet.ShouldContinue* Aufruf eine zusätzliche Überprüfung auf potenziell gefährliche Änderungen durch. Diese Methode wird von keiner Benutzereinstellung oder dem WhatIf Parameter gesteuert. Wenn Ihr Cmdlet die System.Management.Automation.Cmdlet.ShouldContinue*-Methode aufruft, sollte ein Force Parameter vorhanden sein, der die Aufrufe dieser beiden Methoden umgeht und mit dem Vorgang fortfährt. Dies ist wichtig, da ihr Cmdlet in nicht interaktiven Skripts und Hosts verwendet werden kann.

Wenn Ihre Cmdlets diese Aufrufe unterstützen, kann der Benutzer ermitteln, ob die Aktion tatsächlich ausgeführt werden soll. Beispielsweise ruft das cmdlet Stop-Process die System.Management.Automation.Cmdlet.ShouldContinue* Methode auf, bevor eine Reihe kritischer Prozesse beendet wird, einschließlich der Prozesse "System", "Winlogon" und "Spoolsv".

Weitere Informationen zur Unterstützung dieser Methoden finden Sie unter Anfordern von Bestätigungs-.

Support Force-Parameter für interaktive Sitzungen (RD05)

Wenn Ihr Cmdlet interaktiv verwendet wird, stellen Sie immer einen Force-Parameter bereit, um die interaktiven Aktionen außer Kraft zu setzen, z. B. Eingabeaufforderungen oder Lesezeilen der Eingabe). Dies ist wichtig, da ihr Cmdlet in nicht interaktiven Skripts und Hosts verwendet werden kann. Die folgenden Methoden können von einem interaktiven Host implementiert werden.

Document Output Objects (RD06)

Windows PowerShell verwendet die Objekte, die in die Pipeline geschrieben werden. Damit Benutzer die von den einzelnen Cmdlets zurückgegebenen Objekte nutzen können, müssen Sie die zurückgegebenen Objekte dokumentieren und dokumentieren, wofür die Member dieser zurückgegebenen Objekte verwendet werden.

Coderichtlinien

Die folgenden Richtlinien müssen beim Schreiben von Cmdlet-Code befolgt werden. Wenn Sie eine Coderichtlinie finden, die für Ihre Situation gilt, sollten Sie sich die Entwurfsrichtlinien für ähnliche Richtlinien ansehen.

Abgeleitet von den Cmdlet- oder PSCmdlet-Klassen (RC01)

Ein Cmdlet muss entweder vom System.Management.Automation.Cmdlet oder System.Management.Automation.PSCmdlet Basisklasse abgeleitet werden. Cmdlets, die vom System.Management.Automation.Cmdlet abgeleitet werden, Klasse hängen nicht von der Windows PowerShell-Laufzeit ab. Sie können direkt von jeder Microsoft .NET Framework-Sprache aufgerufen werden. Cmdlets, die von der System.Management.Automation.PSCmdlet Klasse abgeleitet werden, hängen von der Windows PowerShell-Laufzeit ab. Daher werden sie innerhalb eines Runspaces ausgeführt.

Alle cmdlet-Klassen, die Sie implementieren, müssen öffentliche Klassen sein. Weitere Informationen zu diesen Cmdlet-Klassen finden Sie unter Cmdlet Overview.

Angeben des Cmdlet-Attributs (RC02)

Damit ein Cmdlet von Windows PowerShell erkannt wird, muss die .NET Framework-Klasse mit dem Cmdlet-Attribut versehen werden. Dieses Attribut gibt die folgenden Features des Cmdlets an.

  • Das Verb- und Nomenpaar, das das Cmdlet identifiziert.

  • Der Standardparametersatz, der verwendet wird, wenn mehrere Parametersätze angegeben werden. Der Standardparametersatz wird verwendet, wenn Windows PowerShell nicht über genügend Informationen verfügt, um zu bestimmen, welcher Parameter verwendet werden soll.

  • Gibt an, ob das Cmdlet Aufrufe der System.Management.Automation.Cmdlet.ShouldProcess*-Methode unterstützt. Diese Methode zeigt dem Benutzer eine Bestätigungsmeldung an, bevor das Cmdlet eine Änderung am System vor nimmt. Weitere Informationen dazu, wie Bestätigungsanfragen gestellt werden, finden Sie unter Anfordern einer Bestätigung.

  • Geben Sie die Auswirkungsebene (oder den Schweregrad) der Aktion an, die der Bestätigungsmeldung zugeordnet ist. In den meisten Fällen sollte der Standardwert von Medium verwendet werden. Weitere Informationen dazu, wie sich die Auswirkungsstufe auf die Bestätigungsanforderungen auswirkt, die dem Benutzer angezeigt werden, finden Sie unter Anfordern der Bestätigung.

Weitere Informationen zum Deklarieren des Cmdlet-Attributs finden Sie unter CmdletAttribute-Deklaration.

Überschreiben einer Eingabeverarbeitungsmethode (RC03)

Damit das Cmdlet an der Windows PowerShell-Umgebung teilnimmt, muss es mindestens eine der folgenden Eingabeverarbeitungsmethodenüberschreiben.

System.Management.Automation.Cmdlet.BeginProcessing Diese Methode wird einmal aufgerufen, und sie wird verwendet, um Vorverarbeitungsfunktionen bereitzustellen.

System.Management.Automation.Cmdlet.ProcessRecord Diese Methode wird mehrmals aufgerufen und dient zur Bereitstellung von Datensatz-nach-Datensatz-Funktionen.

System.Management.Automation.Cmdlet.EndProcessing Diese Methode wird einmal aufgerufen, und sie wird verwendet, um nach der Verarbeitung Funktionen bereitzustellen.

Angeben des OutputType-Attributs (RC04)

Das OutputType-Attribut (eingeführt in Windows PowerShell 2.0) gibt den .NET Framework-Typ an, den Ihr Cmdlet an die Pipeline zurückgibt. Indem Sie den Ausgabetyp Ihrer Cmdlets angeben, können Sie die von Ihrem Cmdlet zurückgegebenen Objekte durch andere Cmdlets besser auffindbar machen. Weitere Informationen zum Dekorieren der Cmdlet-Klasse mit diesem Attribut finden Sie unter OutputType-Attributdeklaration.

Ziehpunkte für Ausgabeobjekte (RC05) nicht beibehalten

Ihr Cmdlet sollte keine Handles an die Objekte beibehalten, die an die System.Management.Automation.Cmdlet.WriteObject*-Methode übergeben werden. Diese Objekte werden an das nächste Cmdlet in der Pipeline übergeben oder von einem Skript verwendet. Wenn Sie die Handles für die Objekte beibehalten, besitzen zwei Entitäten jedes Objekt, was Fehler verursacht.

Robuste Behandlung von Fehlern (RC06)

Eine Verwaltungsumgebung erkennt und nimmt wichtige Änderungen am System vor, das Sie verwalten. Daher ist es wichtig, dass Cmdlets Fehler richtig behandeln. Weitere Informationen zu Fehlerdatensätzen finden Sie unter Windows PowerShell-Fehlerberichterstattung.

Ein System.Management.Automation.ErrorRecord-Objekt erfordert auch eine Fehlerkategorie, die Fehler für den Benutzer gruppiert. Der Benutzer kann Fehler basierend auf der Kategorie anzeigen, indem er den Wert der $ErrorView Shellvariable auf CategoryView festlegt. Die möglichen Kategorien werden durch die System.Management.Automation.ErrorCategory Enumeration definiert.

  • Wenn ein Cmdlet einen neuen Thread erstellt und der Code, der in diesem Thread ausgeführt wird, eine ausnahmefehlerige Ausnahme auslöst, wird der Fehler von Windows PowerShell nicht erfasst und der Prozess beendet.

  • Wenn ein Objekt Code in seinem Destruktor enthält, der eine unbehandelte Ausnahme verursacht, fängt Windows PowerShell den Fehler nicht ab und beendet den Prozess. Dies tritt auch auf, wenn ein Objekt Dispose-Methoden aufruft, die eine unbehandelte Ausnahme verursachen.

Verwenden eines Windows PowerShell-Moduls zum Bereitstellen Ihrer Cmdlets (RC07)

Erstellen Sie ein Windows PowerShell-Modul, um Ihre Cmdlets zu packen und bereitzustellen. Die Unterstützung für Module wird in Windows PowerShell 2.0 eingeführt. Sie können die Assemblys verwenden, die Ihre Cmdlet-Klassen direkt als Binärmoduldateien enthalten (dies ist beim Testen ihrer Cmdlets sehr nützlich), oder Sie können ein Modulmanifest erstellen, das auf die Cmdlet-Assemblys verweist. (Sie können auch vorhandene Snap-In-Assemblys hinzufügen, wenn Sie Module verwenden.) Weitere Informationen zu Modulen finden Sie unter Schreiben eines Windows PowerShell-Moduls.

Siehe auch

Richtlinien für beratungsbezogene Entwicklung

Schreiben eines Windows PowerShell-Cmdlets

  • Last updated on