Empfohlene Entwicklungsrichtlinien

In diesem Abschnitt werden Richtlinien beschrieben, die Sie berücksichtigen sollten, um eine gute Entwicklung und Benutzererfahrung zu gewährleisten. Manchmal können sie angewendet werden und manchmal nicht.

Entwurfsrichtlinien

Die folgenden Richtlinien sollten beim Entwerfen von Cmdlets berücksichtigt werden. Wenn Sie eine Designrichtlinie finden, die für Ihre Situation gilt, sollten Sie sich die Coderichtlinien für ähnliche Richtlinien ansehen.

Unterstützung eines InputObject-Parameters (AD01)

Da Windows PowerShell direkt mit Microsoft .NET Framework-Objekten funktioniert, ist ein .NET Framework-Objekt häufig verfügbar, das genau dem Typ entspricht, den der Benutzer für einen bestimmten Vorgang benötigt. InputObject ist der Standardname für einen Parameter, der ein solches Objekt als Eingabe verwendet. Beispielsweise definiert das Beispiel-Cmdlet Stop-Proc im StopProc-Lernprogramm einen InputObject Parameter vom Typ "Process", der die Eingabe aus der Pipeline unterstützt. Der Benutzer kann eine Gruppe von Prozessobjekten abrufen, bearbeiten, um die genauen Objekte auszuwählen, die beendet werden sollen, und übergeben sie dann direkt an das Stop-Proc Cmdlet.

Unterstützen des Force-Parameters (AD02)

Gelegentlich muss ein Cmdlet den Benutzer vor dem Ausführen 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.

Das Cmdlet Remove-Item entfernt z. B. normalerweise keine schreibgeschützte Datei. Dieses Cmdlet unterstützt jedoch einen Force-Parameter , sodass 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 Parameter Force keine Auswirkung.

Behandeln von Anmeldeinformationen über Windows PowerShell (AD03)

Ein Cmdlet sollte einen Credential Parameter definieren, der Anmeldeinformationen darstellt. Dieser Parameter muss vom Typ System.Management.Automation.PSCredential sein und muss mithilfe einer Credential-Attributdeklaration definiert werden. Diese Unterstützung fordert den Benutzer automatisch zur Eingabe des Benutzernamens, zum Kennwort oder für beides auf, wenn keine vollständigen Anmeldeinformationen direkt angegeben werden. Weitere Informationen zum Attribut "Credential" finden Sie unter Credential-Attributdeklaration.

Unterstützung von Codierungsparametern (AD04)

Wenn Ihr Cmdlet Text in oder aus einem binären Formular liest oder schreibt, z. B. schreiben oder aus einer Datei in einem Dateisystem lesen, muss Ihr Cmdlet über einen Codierungsparameter verfügen, der angibt, wie der Text in der Binärform codiert wird.

Test-Cmdlets sollten einen booleschen Wert (AD05) zurückgeben.

Cmdlets, die Tests mit ihren 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, sollten Sie sich die Designrichtlinien für ähnliche Richtlinien ansehen.

Befolgen von Benennungskonventionen für Cmdlet-Klassen (AC01)

Indem Sie standardbenennungskonventionen befolgen, machen Sie Ihre Cmdlets leichter auffindbar, und Sie helfen dem Benutzer, genau zu verstehen, was die Cmdlets tun. Diese Vorgehensweise ist besonders wichtig für andere Entwickler, die Windows PowerShell verwenden, 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 an den Namespace angefügt wird .Commands , der das Produkt darstellt, in dem das Cmdlet ausgeführt wird. Cmdlets, die in Windows PowerShell enthalten sind, werden beispielsweise im Microsoft.PowerShell.Commands Namespace definiert.

Geben Sie der Cmdlet-Klasse einen Namen, der dem Cmdlet-Namen entspricht.

Wenn Sie die .NET Framework-Klasse benennen, die ein Cmdlet implementiert, benennen Sie die Klasse <Verb><Noun>Command, wobei Sie die <Verb> Und <Noun> Platzhalter durch das Verb und das Substantiv ersetzen, das für den Cmdlet-Namen verwendet wird. Beispielsweise wird das Cmdlet Get-Process von einer Klasse implementiert, die aufgerufen wird GetProcessCommand.

If No Pipeline Input Override the BeginProcessing Method (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 Windows PowerShell das Verwalten der Sortierung zwischen Cmdlets. Das erste Cmdlet in der Pipeline gibt immer seine Objekte zurück, bevor die verbleibenden Cmdlets in der Pipeline die Möglichkeit erhalten, die Verarbeitung zu starten.

So behandeln Sie Stoppanforderungen überschreiben die StopProcessing-Methode (AC03)

Überschreiben Sie die System.Management.Automation.Cmdlet.StopProcessing-Methode , damit Ihr Cmdlet das Stoppsignal verarbeiten kann. Einige Cmdlets dauern eine lange Zeit, um den Vorgang abzuschließen, und sie lassen eine lange Zeit zwischen Aufrufen der Windows PowerShell-Laufzeit bestehen, z. B. wenn das Cmdlet den Thread in lang ausgeführten RPC-Aufrufen blockiert. Dazu gehören Cmdlets, die Aufrufe an die System.Management.Automation.Cmdlet.WriteObject-Methode , an die Methode "System.Management.Automation.Cmdlet.WriteError " und andere Feedbackmechanismen ausführen, die eine lange Zeit in Anspruch nehmen können. 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, ist möglicherweise zusätzliche Objektentsorgung erforderlich. Wenn Ihr Cmdlet beispielsweise ein Dateihandle in der System.Management.Automation.Cmdlet.BeginProcessing-Methode öffnet und das Handle für die Verwendung durch die Methode System.Management.Automation.Cmdlet.ProcessRecord geöffnet hält, muss dieses Handle am Ende der Verarbeitung geschlossen werden.

Die Windows PowerShell-Laufzeit ruft nicht immer die System.Management.Automation.Cmdlet.EndProcessing-Methode auf. Beispielsweise wird die System.Management.Automation.Cmdlet.EndProcessing-Methode möglicherweise nicht aufgerufen, wenn das Cmdlet in der Mitte des Vorgangs abgebrochen wird oder wenn ein Beendigungsfehler in einem Teil des Cmdlets auftritt. Daher sollte die .NET Framework-Klasse für ein Cmdlet, das die Objektbereinigung erfordert, das vollständige System.IDisposable-Schnittstellenmuster implementieren, einschließlich des Finalizers, damit die Windows PowerShell-Laufzeit sowohl die Methoden System.Management.Automation.Cmdlet.EndProcessing als auch System.IDisposable.Dispose* am Ende der Verarbeitung aufrufen kann.

Serialisierungsfreundliche Parametertypen (AC05) verwenden

Um das Ausführen Ihres Cmdlets auf Remotecomputern zu unterstützen, verwenden Sie Typen, die auf dem Clientcomputer serialisiert und dann auf dem Servercomputer neu hydratisiert werden können. Die folgenden Typen sind serialisierungsfreundlich.

Grundtypen:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 und UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri und Version.
• Char, String, XmlDocument.

Integrierte rehydratierbare Typen:

• PSPrimitiveDictionary
• Schalter-Parameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Andere Typen:

• SecureString
• Container (Listen und Wörterbücher des obigen Typs)

Verwenden von SecureString für vertrauliche Daten (AC06)

Bei der Verarbeitung vertraulicher Daten verwenden Sie immer den Datentyp "System.Security.SecureString ". Dazu können Pipelineeingaben an Parameter sowie das Zurückgeben vertraulicher Daten an die Pipeline gehören.

Während .NET die Verwendung von SecureString für die neue Entwicklung empfiehlt, unterstützt PowerShell weiterhin die SecureString-Klasse zur Abwärtskompatibilität. Die Verwendung der SecureString-Klasse ist immer noch sicherer als die Verwendung einer Nur-Text-Zeichenfolge. PowerShell basiert weiterhin auf dem SecureString-Typ , um versehentlich die Inhalte der Konsole oder in Protokollen verfügbar zu machen. Verwenden Sie SecureString sorgfältig, da sie problemlos in eine Nur-Text-Zeichenfolge konvertiert werden kann. Eine vollständige Erläuterung zur Verwendung von SecureString finden Sie in der Dokumentation zur System.Security.SecureString-Klasse.

Siehe auch

Erforderliche Entwicklungsrichtlinien

Schreiben eines Windows PowerShell-Cmdlets