Empfohlene Entwicklungsrichtlinien
In diesem Abschnitt werden Richtlinien beschrieben, die Sie berücksichtigen sollten, um eine gute Entwicklungs- und Benutzererfahrung sicherzustellen. Manchmal können sie angewendet werden, manchmal auch nicht.
Entwurfsrichtlinien
Beim Entwerfen von Cmdlets sollten die folgenden Richtlinien berücksichtigt werden. Wenn Sie eine Entwurfsrichtlinie finden, die für Ihre Situation gilt, sehen Sie sich die Coderichtlinien für ähnliche Richtlinien an.
Unterstützung eines InputObject-Parameters (AD01)
Da Windows PowerShell direkt mit Microsoft .NET Framework-Objekten arbeitet, ist häufig ein .NET Framework-Objekt verfügbar, das genau dem Typ entspricht, den der Benutzer zum Ausführen eines bestimmten Vorgangs benötigt. InputObject ist der Standardname für einen Parameter, der ein solches Objekt als Eingabe akzeptiert.
Das Beispiel-Cmdlet im Stop-Proc StopProc-Tutorial definiert beispielsweise einen Parameter vom Typ Process, der die Eingabe InputObject aus der Pipeline unterstützt. Der Benutzer kann eine Reihe von Prozessobjekten abrufen, sie bearbeiten, um die genauen Objekte auszuwählen, die sie beenden möchten, und sie dann direkt an das Stop-Proc Cmdlet übergeben.
Unterstützung des Force-Parameters (AD02)
Gelegentlich muss ein Cmdlet den Benutzer vor der Ausführung eines angeforderten Vorgangs schützen. Ein solches Cmdlet sollte einen Force-Parameter unterstützen, damit der Benutzer diesen Schutz außer Kraft setzen kann, wenn der Benutzer über Berechtigungen zum Ausführen des Vorgangs verfügt.
Beispielsweise entfernt das Remove-Item-Cmdlet normalerweise keine schreibgeschützte Datei. Dieses Cmdlet unterstützt jedoch einen Force-Parameter, damit ein Benutzer das Entfernen einer schreibgeschützten Datei erzwingen kann. Wenn der Benutzer bereits über die Berechtigung zum Ändern des schreibgeschützten Attributs verfügt und der Benutzer die Datei entfernt, vereinfacht die Verwendung des Force-Parameters den Vorgang. Wenn der Benutzer jedoch nicht über die Berechtigung zum Entfernen der Datei verfügt, hat der Force-Parameter keine Auswirkungen.
Verarbeiten von Anmeldeinformationen über Windows PowerShell (AD03)
Ein Cmdlet sollte einen Parameter Credential definieren, um Anmeldeinformationen anzugeben. Dieser Parameter muss vom Typ System.Management.Automation.PSCredential sein und mithilfe einer Attributdeklaration für Anmeldeinformationen definiert werden. Diese Unterstützung fordert den Benutzer automatisch zur Eingabe des Benutzernamens, des Kennworts oder für beides auf, wenn keine vollständigen Anmeldeinformationen direkt angegeben werden. Weitere Informationen zum Credential-Attribut finden Sie unter Credential Attribute Declaration.
Unterstützung von Codierungsparametern (AD04)
Wenn Ihr Cmdlet Text in oder aus einer binären Form liest oder schreibt, z. B. in eine Datei in einem Dateisystem schreiben oder daraus lesen, muss Ihr Cmdlet über einen Encoding-Parameter verfügen, der angibt, wie der Text in der binären Form codiert wird.
Test-Cmdlets sollten einen booleschen Wert zurückgeben (AD05)
Cmdlets, die Tests für ihre Ressourcen ausführen, sollten einen System.Boolean-Typ an die Pipeline zurückgeben, damit sie in bedingten Ausdrücken verwendet werden können.
Coderichtlinien
Die folgenden Richtlinien sollten beim Schreiben von Cmdlet-Code berücksichtigt werden. Wenn Sie eine Richtlinie finden, die für Ihre Situation gilt, sehen Sie sich die Entwurfsrichtlinien für ähnliche Richtlinien an.
Befolgen von Cmdlet-Klassenbenennungskonventionen (AC01)
Indem Sie die Standardbenennungskonventionen verwenden, machen Sie Ihre Cmdlets besser aufsetzbar und helfen dem Benutzer, genau zu verstehen, was die Cmdlets tun. Diese Vorgehensweise ist besonders wichtig für andere Entwickler, die Windows PowerShell, da Cmdlets öffentliche Typen sind.
Definieren eines Cmdlets im richtigen Namespace
Normalerweise definieren Sie die -Klasse für ein Cmdlet in einem .NET Framework Namespace, der "" anfügen. Befehle" in den Namespace, der das Produkt darstellt, in dem das Cmdlet ausgeführt wird. Beispielsweise werden Cmdlets, die in Windows PowerShell enthalten sind, im -Namespace Microsoft.PowerShell.Commands definiert.
Benennen Sie die Cmdlet-Klasse so, dass sie mit dem Cmdlet-Namen übereinstimmen soll.
Wenn Sie die .NET Framework-Klasse benennen, die ein Cmdlet implementiert, nennen Sie die Klasse " ", wobei Sie die Platzhalter und durch das Verb und das Substantiv ersetzen, die für den Cmdlet-Namen <Verb><Noun><Command> <Verb> verwendet <Noun> werden. Das Cmdlet Get-Process wird beispielsweise durch eine Klasse namens GetProcessCommand implementiert.
Wenn keine Pipelineeingabe die BeginProcessing-Methode überschreibt (AC02)
Wenn Ihr Cmdlet keine Eingaben aus der Pipeline akzeptiert, sollte die Verarbeitung in der System.Management.Automation.Cmdlet.BeginProcessing-Methode implementiert werden. Die Verwendung dieser Methode ermöglicht es Windows PowerShell, die Reihenfolge zwischen Cmdlets zu verwalten. Das erste Cmdlet in der Pipeline gibt seine Objekte immer zurück, bevor die verbleibenden Cmdlets in der Pipeline die Möglichkeit erhalten, ihre Verarbeitung zu starten.
So behandeln Sie Stoppanforderungen Überschreiben der StopProcessing-Methode (AC03)
Überschreiben Sie die System.Management.Automation.Cmdlet.StopProcessing-Methode, damit Ihr Cmdlet das Stoppsignal verarbeiten kann. Einige Cmdlets nehmen lange Zeit in Zeit, um ihren Vorgang auszuführen, und sie lassen eine lange Zeit zwischen Aufrufen der Windows PowerShell-Runtime vergehen, z. B. wenn das Cmdlet den Thread in RPC-Aufrufen mit langer Ausführungszeit blockiert. Dies umfasst Cmdlets, die Aufrufe an die System.Management.Automation.Cmdlet.WriteObject-Methode, an die System.Management.Automation.Cmdlet.WriteError-Methode und an andere Feedbackmechanismen senden, deren Abschluss lange dauern kann. In diesen Fällen muss der Benutzer möglicherweise ein Stoppsignal an diese Cmdlets senden.
Implementieren der IDisposable-Schnittstelle (AC04)
Wenn Ihr Cmdlet Objekte enthält, die nicht von der System.Management.Automation.Cmdlet.ProcessRecord-Methode verworfen (in die Pipeline geschrieben) werden, erfordert Ihr Cmdlet möglicherweise eine zusätzliche Objektentfernung. Wenn Ihr Cmdlet beispielsweise ein Dateihand handle in seiner System.Management.Automation.Cmdlet.BeginProcessing-Methode öffnet und das Handle für die Verwendung durch die System.Management.Automation.Cmdlet.ProcessRecord-Methode geöffnet hält, muss dieses Handle am Ende der Verarbeitung geschlossen werden.
Die Windows PowerShell Runtime aufruft nicht immer die System.Management.Automation.Cmdlet.EndProcessing-Methode. Beispielsweise wird die System.Management.Automation.Cmdlet.EndProcessing-Methode möglicherweise nicht aufgerufen, wenn das Cmdlet während des Vorgangs abgebrochen wird oder wenn in einem Teil des Cmdlets ein Abbruchfehler auftritt. Daher sollte die .NET Framework-Klasse für ein Cmdlet, das eine Objektbereinigung erfordert, das vollständige System.IDisposable-Schnittstellenmuster implementieren, einschließlich des Finalizers, damit die Windows PowerShell-Runtime am Ende der Verarbeitung sowohl die Methoden System.Management.Automation.Cmdlet.EndProcessing als auch System.IDisposable.Dispose* aufrufen kann.
Serialisierungsfreundliche Parametertypen verwenden (AC05)
Um die Ausführung Ihres Cmdlets auf Remotecomputern zu unterstützen, verwenden Sie Typen, die einfach auf dem Clientcomputer serialisiert und dann auf dem Servercomputer aktiviert werden können. Die folgenden Typen sind serialisierungsfreundliche Typen.
Primitive Typen:
Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 und UInt64.
Boolean, Guid, Byte[], TimeSpan, DateTime, Uri und Version.
Char, String, XmlDocument.
Integrierte befähige Typen:
PSPrimitiveDictionary
SwitchParameter
PSListModifier
PSCredential
IPAddress, MailAddress
CultureInfo
X509Certificate2, X500DistinguishedName
DirectorySecurity, FileSecurity, RegistrySecurity
Andere Typen:
SecureString
Container (Listen und Wörterbücher des oben genannten Typs)
Verwenden von SecureString für sensible Daten (AC06)
Verwenden Sie beim Verarbeiten vertraulicher Daten immer den Datentyp System.Security.Securestring. Dies kann die Pipelineeingabe für Parameter sowie die Rückgabe vertraulicher Daten an die Pipeline umfassen.
Siehe auch
Erforderliche Entwicklungsrichtlinien
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für