Hinzufügen von Aliasen, Platzhaltererweiterung und Hilfe zu Cmdlet-Parametern

  • Artikel

In diesem Abschnitt wird beschrieben, wie Sie Aliase, Wildcarderweiterung und Hilfemeldungen zu den Parametern des Stop-Proc Cmdlets hinzufügen (beschrieben in "Erstellen eines Cmdlets", das das System ändert).

Dieses Stop-Proc Cmdlet versucht, Prozesse zu beenden, die mithilfe des Get-Proc Cmdlets abgerufen werden (beschrieben im Erstellen Ihres ersten Cmdlets).

Definieren des Cmdlets

Der erste Schritt bei der Cmdleterstellung ist immer das Benennen des Cmdlets und das Deklarieren der .NET-Klasse, die das Cmdlet implementiert. Da Sie ein Cmdlet schreiben, um das System zu ändern, sollte es entsprechend benannt werden. Da dieses Cmdlet die Systemprozesse beendet, verwendet es das Verb Stop, das durch die System.Management.Automation.Verbslifecycle-Klasse definiert ist, mit dem Nomen Proc , um den Prozess anzugeben. Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet-Verbnamen.

Der folgende Code ist die Klassendefinition für dieses Stop-Proc Cmdlet.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Definieren von Parametern für Systemänderung

Ihr Cmdlet muss Parameter definieren, die Systemänderungen und Benutzerfeedback unterstützen. Das Cmdlet sollte einen Name-Parameter oder eine Äquivalente definieren, damit das Cmdlet das System durch eine Art Bezeichner ändern kann. Darüber hinaus sollte das Cmdlet die Parameter Force und PassThru definieren. Weitere Informationen zu diesen Parametern finden Sie unter Erstellen eines Cmdlets, das das System ändert.

Definieren eines Parameteralias

Ein Parameteralias kann ein alternativer Name oder ein gut definierter 1-Buchstaben- oder 2-Buchstaben-Kurzname für einen Cmdlet-Parameter sein. In beiden Fällen ist das Ziel, aliase zu verwenden, um die Benutzereingabe über die Befehlszeile zu vereinfachen. Windows PowerShell unterstützt Parameteralias über das Attribut System.Management.Automation.Aliasattribute, das die Deklarationssyntax [Alias()]verwendet.

Der folgende Code zeigt, wie ein Alias dem Parameter Name hinzugefügt wird.

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Zusätzlich zur Verwendung des System.Management.Automation.Aliasattribute-Attributs führt die Windows PowerShell Laufzeit einen Teilnamenabgleich durch, auch wenn keine Aliase angegeben werden. Wenn Ihr Cmdlet z. B. einen FileName-Parameter aufweist und der einzige Parameter ist, mit dem gestartet wirdF, kann der Benutzer den Eintrag als FileName-Parameter eingebenFilename, Filenam``Fi``Fileoder F er kann den Eintrag trotzdem als FileName-Parameter erkennen.

Erstellen von Hilfe für Parameter

Windows PowerShell ermöglicht es Ihnen, Hilfe für Cmdlet-Parameter zu erstellen. Führen Sie dies für jeden Parameter aus, der für Systemänderungen und Benutzerfeedback verwendet wird. Damit jeder Parameter Hilfe unterstützt, können Sie das HelpMessage-Attributschlüsselwort in der Deklaration des Attributs System.Management.Automation.Parameterattribute festlegen. Dieses Schlüsselwort definiert den Text, der dem Benutzer zur Unterstützung bei der Verwendung des Parameters angezeigt werden soll. Sie können auch das HelpMessageBaseName-Schlüsselwort festlegen, um den Basisnamen einer Ressource zu identifizieren, die für die Nachricht verwendet werden soll. Wenn Sie dieses Schlüsselwort festlegen, müssen Sie auch das HelpMessageResourceId-Schlüsselwort festlegen, um den Ressourcenbezeichner anzugeben.

Der folgende Code aus diesem Stop-Proc Cmdlet definiert das HelpMessage-Attributwort für den Parameter Name .

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

Überschreiben einer Eingabeverarbeitungsmethode

Ihr Cmdlet muss eine Eingabeverarbeitungsmethode außer Kraft setzen. Dies ist meist System.Management.Automation.Cmdlet.ProcessRecord. Beim Ändern des Systems sollte das Cmdlet die Methoden "System.Management.Automation.Cmdlet.ShouldProcess " und "System.Management.Automation.Cmdlet.ShouldContinue " aufrufen, damit der Benutzer Feedback bereitstellen kann, bevor eine Änderung vorgenommen wird. Weitere Informationen zu diesen Methoden finden Sie unter Erstellen eines Cmdlets, das das System ändert.

Unterstützung der Wildcarderweiterung

Um die Auswahl mehrerer Objekte zuzulassen, kann Ihr Cmdlet die Klassen System.Management.Automation.WildcardPattern und System.Management.Automation.WildcardOptions verwenden, um die Unterstützung der Wildcarderweiterung für die Parametereingabe bereitzustellen. Beispiele für Wildcardmuster sind lsa*, *.txtund [a-c]*. Verwenden Sie das Zurück-Anführungszeichen (`) als Escapezeichen, wenn das Muster ein Zeichen enthält, das buchstäblich verwendet werden soll.

Wildcarderweiterungen von Datei- und Pfadnamen sind Beispiele für allgemeine Szenarien, in denen das Cmdlet möglicherweise die Unterstützung für Pfadeingaben zulassen möchte, wenn die Auswahl mehrerer Objekte erforderlich ist. Ein allgemeiner Fall befindet sich im Dateisystem, in dem ein Benutzer alle Dateien im aktuellen Ordner sehen möchte.

Sie sollten nur selten eine angepasste Wildcardmusterabgleichsimplementierung benötigen. In diesem Fall sollte Ihr Cmdlet entweder die vollständige POSIX 1003.2, 3.13-Spezifikation für die Wildcarderweiterung oder die folgende vereinfachte Teilmenge unterstützen:

  • Fragezeichen (?). Entspricht einem beliebigen Zeichen an der angegebenen Position.
  • Sternchen (*). Entspricht null oder mehr Zeichen, die an der angegebenen Position beginnen.
  • Öffnen Sie die Klammer ([). Führt einen Musterklammerausdruck ein, der Zeichen oder einen Zeichenbereich enthalten kann. Wenn ein Bereich erforderlich ist, wird ein Bindestrich (-) verwendet, um den Bereich anzugeben.
  • Schließen Sie die Klammer (]). Endet ein Musterklammerausdruck.
  • Zurück-Anführungszeichen escapezeichen (`). Gibt an, dass das nächste Zeichen buchstäblich genommen werden soll. Beachten Sie, dass beim Angeben des Back-Anführungszeichens aus der Befehlszeile (im Gegensatz zur programmgesteuerten Angabe) das Escapezeichen "Zurück-Anführungszeichen" zweimal angegeben werden muss.

Hinweis

Weitere Informationen zu Wildcardmustern finden Sie unter Unterstützen von Wildcards in Cmdlet-Parametern.

Der folgende Code zeigt, wie Sie Wildcardoptionen festlegen und das Zum Auflösen des Namensparameters für dieses Cmdlet verwendete Wildcardmuster definieren.

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

Der folgende Code zeigt, wie Sie testen, ob der Prozessname dem definierten Platzhaltermuster entspricht. Beachten Sie, dass in diesem Fall, wenn der Prozessname nicht mit dem Muster übereinstimmt, das Cmdlet weiterhin den nächsten Prozessnamen erhält.

if (!wildcard.IsMatch(processName))
{
  continue;
}

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie im StopProcessSample03-Beispiel.

Definieren von Objekttypen und Formatierungen

Windows PowerShell übergibt Informationen zwischen Cmdlets mit .Net-Objekten. Daher muss ein Cmdlet möglicherweise seinen eigenen Typ definieren, oder das Cmdlet muss möglicherweise einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder Erweitern vorhandener Typen finden Sie unter Erweitern von Objekttypen und Formatierungen.

Erstellen des Cmdlets

Nach der Implementierung eines Cmdlets muss es über ein Windows PowerShell-Snap-In mit Windows PowerShell registriert werden. Weitere Informationen zum Registrieren von Cmdlets finden Sie unter Registrieren von Cmdlets, Anbietern und Hostanwendungen.

Testen des Cmdlets

Wenn Ihr Cmdlet mit Windows PowerShell registriert wurde, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Testen wir das Beispiel Stop-Proc Cmdlets. Weitere Informationen zum Verwenden von Cmdlets aus der Befehlszeile finden Sie im Erste Schritte mit Windows PowerShell.

  • Starten Sie Windows PowerShell, und verwenden Stop-Proc Sie diesen, um einen Prozess mithilfe des ProcessName-Alias für den Parameter Name zu beenden.

    PS> Stop-Proc -ProcessName notepad

    Die folgende Ausgabe wird angezeigt.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (3496)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

  • Führen Sie den folgenden Eintrag in der Befehlszeile aus. Da der Parameter Name obligatorisch ist, werden Sie dazu aufgefordert. Das Eingeben !? des Hilfetexts, der dem Parameter zugeordnet ist, wird angezeigt.

    PS> Stop-Proc

    Die folgende Ausgabe wird angezeigt.

    Cmdlet Stop-Proc at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
Name[0]: !?
The name of one or more processes to stop. Wildcards are permitted.
Name[0]: notepad

  • Nehmen Sie nun den folgenden Eintrag vor, um alle Prozesse zu beenden, die dem Wildcardmuster *note*entsprechen. Sie werden aufgefordert, bevor Sie jeden Prozess beenden, der dem Muster entspricht.

    PS> Stop-Proc -Name *note*

    Die folgende Ausgabe wird angezeigt.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (1112)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y

    Die folgende Ausgabe wird angezeigt.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

    Die folgende Ausgabe wird angezeigt.

    Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N

Weitere Informationen