Erforderliche Entwicklungsrichtlinien
Die folgenden Richtlinien müssen beim Schreiben Ihrer Cmdlets befolgt werden. Sie sind in Richtlinien zum Entwerfen von Cmdlets und Richtlinien zum Schreiben ihres Cmdlet-Codes getrennt. 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 Entwurfsrichtlinie finden, die für Ihre Situation gilt, sehen Sie sich die Coderichtlinien für ähnliche Richtlinien an.
Nur genehmigte Verben verwenden (RD01)
Das im Cmdlet-Attribut angegebene Verb muss aus dem erkannten Satz von Verben stammen, die von der Windows PowerShell. Es darf keins der unzulässigen Synonyme sein. Verwenden Sie die konstanten Zeichenfolgen, die durch die folgenden Enumerationen definiert werden, um Cmdlet-Verben anzugeben:
Weitere Informationen zu den genehmigten Verbnamen finden Sie unter Cmdlet-Verben.
Benutzer benötigen einen Satz erkennbarer und erwarteter Cmdlet-Namen. Verwenden Sie das entsprechende Verb, damit der Benutzer schnell eine Bewertung der Funktionen eines Cmdlets ausführen und die Funktionen des Systems leicht erkennen kann. Der folgende Befehlszeilenbefehl ruft beispielsweise eine Liste aller Befehle im System ab, deren Namen mit "start" beginnen: get-command start-* . Verwenden Sie die Nomen in Ihren Cmdlets, um Ihre Cmdlets von anderen Cmdlets zu unterscheiden. Das Nomen 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.
| Zeichen | Name |
|---|---|
| # | Nummernzeichen |
| , | Komma |
| () | Klammern |
| {} | Klammern |
| [] | Klammern |
| & | Und-zeichen |
| - | Bindestrich Hinweis: Der Bindestrich kann verwendet werden, um das Verb vom Substantiv zu trennen, aber nicht innerhalb des Substantivs oder innerhalb des Verbs. |
| / | Schrägstrich |
| \ | schräger Schrägstrich |
| $ | Dollarzeichen |
| ^ | Caretzeichen |
| ; | Semikolon |
| : | Doppelpunkt |
| " | Doppeltes Anführungszeichen |
| ' | Einfaches Anführungszeichen |
| <> | Eckige Klammern |
| | | Vertikaler Balken |
| ? | Fragezeichen |
| @ | @-Zeichen |
| ` | Rückstrich (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 nicht die folgenden Namen verwenden: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction und Verbose. Weitere Informationen zu diesen Parametern finden Sie unter Allgemeine Parameternamen.
Supportbestätigungsanforderungen (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 an fordern, und in besonderen 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 wurde.)
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 der System.Management.Automation.Cmdlet.ShouldProcess*-Methode unterstützt und das Cmdlet den Aufruf der System.Management.Automation.Cmdlet.ShouldProcess*-Methode nicht ausführen kann, kann der Benutzer das System unerwartet ändern.
Verwenden Sie die System.Management.Automation.Cmdlet.ShouldProcess*-Methode für alle Systemänderungen. 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ährlichen Änderungen durch. Diese Methode wird nicht durch eine Benutzereinstellung oder den -Parameter WhatIf gesteuert. Wenn Ihr Cmdlet die System.Management.Automation.Cmdlet.ShouldContinue*-Methode aufruft, sollte es über einen Parameter verfügen, der die Aufrufe dieser beiden Methoden umgeht und mit dem Vorgang fortgesetzt Force wird. 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 bestimmen, ob die Aktion tatsächlich ausgeführt werden soll. Das Cmdlet Stop-Process ruft beispielsweise 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 der Bestätigung.
Support Force-Parameter für interaktive Sitzungen (RD05)
Wenn Ihr Cmdlet interaktiv verwendet wird, geben Sie immer einen Force-Parameter an, um die interaktiven Aktionen außer Kraft zu setzen, z. B. Eingabeaufforderungen oder Lesezeilen von Eingaben). 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.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.Pshostuserinterface.PromptForChoice
System.Management.Automation.Host.Ihostuisupportsmultiplechoiceselection.PromptForChoice
System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*
System.Management.Automation.Host.Pshostuserinterface.ReadLine*
System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*
Dokumentausgabeobjekte (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
Beim Schreiben von Cmdlet-Code müssen die folgenden Richtlinien befolgt werden. Wenn Sie eine Coderichtlinie finden, die für Ihre Situation gilt, sollten Sie sich die Entwurfsrichtlinien für ähnliche Richtlinien ansehen.
Ableiten von cmdlet- oder PSCmdlet-Klassen (RC01)
Ein Cmdlet muss entweder von der Basisklasse System.Management.Automation.Cmdlet oder System.Management.Automation.PSCmdlet abgeleitet werden. Cmdlets, die von der System.Management.Automation.Cmdlet-Klasse abgeleitet werden, sind nicht von der Windows PowerShell Runtime abhängig. Sie können direkt aus jeder Microsoft .NET Framework Sprache aufgerufen werden. Cmdlets, die von der System.Management.Automation.PSCmdlet-Klasse abgeleitet werden, hängen von der Windows PowerShell Runtime ab. Daher werden sie in einem Runspace ausgeführt.
Alle Cmdlet-Klassen, die Sie implementieren, müssen öffentliche Klassen sein. Weitere Informationen zu diesen Cmdlet-Klassen finden Sie unter Cmdlet-Übersicht.
Angeben des Cmdlet-Attributs (RC02)
Damit ein Cmdlet von Windows PowerShell erkannt wird, muss seine .NET Framework-Klasse mit dem Cmdlet-Attribut versehen werden. Dieses Attribut gibt die folgenden Funktionen des Cmdlets an.
Das Verb-Nomen-Paar, 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 Parametersatz 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 vornimmt. Weitere Informationen dazu, wie Bestätigungsanforderungen gestellt werden, finden Sie unter Anfordern einer Bestätigung.
Geben Sie die Auswirkungsstufe (oder den Schweregrad) der Aktion an, die der Bestätigungsmeldung zugeordnet ist. In den meisten Fällen sollte der Standardwert Medium verwendet werden. Weitere Informationen dazu, wie sich die Auswirkungsstufe auf die Bestätigungsanforderungen auswirkt, die dem Benutzer angezeigt werden, finden Sie unter Anfordern einer 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 zur Bereitstellung von Vorverarbeitungsfunktionen verwendet.
System.Management.Automation.Cmdlet.ProcessRecord Diese Methode wird mehrmals aufgerufen und zur Bereitstellung von Datensatz-für-Datensatz-Funktionen verwendet.
System.Management.Automation.Cmdlet.EndProcessing Diese Methode wird einmal aufgerufen und zur Bereitstellung von Nachbearbeitungsfunktionen verwendet.
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, machen Sie die von Ihrem Cmdlet zurückgegebenen Objekte von anderen Cmdlets leichter auffindbar. Weitere Informationen zum Verzieren der Cmdlet-Klasse mit diesem Attribut finden Sie unter OutputType-Attributdeklaration.
Handles für Ausgabeobjekte nicht beibehalten (RC05)
Ihr Cmdlet sollte keine Handles für 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, wodurch Fehler verursacht werden.
Robustes Behandeln von Fehlern (RC06)
Eine Verwaltungsumgebung erkennt und nimmt wichtige Änderungen am System vor, das Sie verwalten. Daher ist es wichtig, dass Cmdlets Fehler ordnungsgemäß behandeln. Weitere Informationen zu Fehlerdatensätzen finden Sie unter Windows PowerShell Fehlerberichterstattung.
Wenn ein Fehler verhindert, dass ein Cmdlet weitere Datensätze weiter verarbeitet, ist dies ein Abbruchfehler. Das Cmdlet muss die Methode System.Management.Automation.Cmdlet.ThrowTerminatingError* aufrufen, die auf ein System.Management.Automation.ErrorRecord-Objekt verweist. Wenn eine Ausnahme nicht vom Cmdlet abgefangen wird, löst die Windows PowerShell Runtime selbst einen Abbruchfehler aus, der weniger Informationen enthält.
Bei einem Fehler ohne Abbruch, bei dem der Vorgang für den nächsten Datensatz, der aus der Pipeline stammt (z. B. ein Datensatz, der von einem anderen Prozess erzeugt wird), nicht beendet wird, muss das Cmdlet die System.Management.Automation.Cmdlet.WriteError*-Methode aufrufen, die auf ein System.Management.Automation.ErrorRecord-Objekt verweist. Ein Beispiel für einen Fehler ohne Abbruch ist der Fehler, der auftritt, wenn ein bestimmter Prozess nicht beendet werden kann. Durch Aufrufen der System.Management.Automation.Cmdlet.WriteError*-Methode kann der Benutzer die angeforderten Aktionen konsistent ausführen und die Informationen für bestimmte Aktionen beibehalten, die fehlschlagen. Ihr Cmdlet sollte jeden Datensatz so unabhängig wie möglich verarbeiten.
Das System.Management.Automation.ErrorRecord-Objekt, auf das von den Methoden System.Management.Automation.Cmdlet.ThrowTerminatingError* und System.Management.Automation.Cmdlet.WriteError* verwiesen wird, erfordert eine Ausnahme im Kern. Befolgen Sie die .NET Framework Entwurfsrichtlinien, wenn Sie die zu verwendende Ausnahme bestimmen. Wenn der Fehler semantisch mit einer vorhandenen Ausnahme identisch ist, verwenden Sie diese Ausnahme, oder leiten Sie sie von dieser Ausnahme ab. Andernfalls leiten Sie eine neue Ausnahme- oder Ausnahmehierarchie direkt vom System.Exception-Typ ab.
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 Shellvariablen 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 nicht behandelte Ausnahme auslöst, fängt Windows PowerShell den Fehler nicht ab und beendet den Prozess.
Wenn ein Objekt code in seinem Destruktor enthält, der eine nicht behandelte 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 nicht behandelte 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, die Ihre Cmdlet-Klassen enthalten, direkt als binäre Moduldateien verwenden (dies ist sehr nützlich, wenn Sie Ihre Cmdlets testen), 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.
Weitere Informationen
Ausdrücklich empfohlene Entwicklungsrichtlinien