Freigeben über

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

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

Dieses Stop-Proc Cmdlet versucht, Prozesse zu beenden, die mithilfe des cmdlets Get-Proc abgerufen werden (beschrieben in Creating Your First Cmdlet).

Definieren des Cmdlets

Der erste Schritt beim Erstellen von Cmdlets ist immer das Benennen des Cmdlets und das Deklarieren der .NET-Klasse, die das Cmdlet implementiert. Da Sie ein Cmdlet zum Ändern des Systems schreiben, sollte es entsprechend benannt werden. Da dieses Cmdlet Systemprozesse beendet, wird das Verb Stopverwendet, das durch die System.Management.Automation.VerbsLifecycle Klasse definiert ist, wobei das Substantiv Proc- zum Angeben des Prozesses verwendet wird. Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet Verb Names.

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 die Systemänderung

Ihr Cmdlet muss Parameter definieren, die Systemänderungen und Benutzerfeedback unterstützen. Das Cmdlet sollte einen Name Parameter oder gleichwertig 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 soll die Verwendung von Aliasen die Benutzereingabe über die Befehlszeile vereinfachen. Windows PowerShell unterstützt Parameteralias über das System.Management.Automation.AliasAttribute Attribut, das die Deklarationssyntax [Alias()]verwendet.

Der folgende Code zeigt, wie dem Parameter Name Name ein Alias 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 teilweisen Namensabgleich durch, auch wenn keine Aliase angegeben werden. Wenn Ihr Cmdlet beispielsweise über einen FileName Parameter verfügt und der einzige Parameter ist, der mit Fbeginnt, kann der Benutzer Filename, Filenam, File, Fioder F eingeben und den Eintrag weiterhin als FileName Parameter erkennen.

Erstellen von Hilfe zu Parametern

Mit Windows PowerShell können Sie Hilfe für Cmdlet-Parameter erstellen. Führen Sie dies für alle Parameter aus, die für Systemänderungen und Benutzerfeedback verwendet werden. Für jeden Parameter zur Unterstützung der Hilfe können Sie das HelpMessage Attributschlüsselwort im System.Management.Automation.ParameterAttribute Attributdeklaration festlegen. Dieses Schlüsselwort definiert den Text, der dem Benutzer angezeigt werden soll, um Unterstützung bei der Verwendung des Parameters zu erhalten. 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 die HelpMessageResourceId Schlüsselwort festlegen, um den Ressourcenbezeichner anzugeben.

Der folgende Code aus diesem cmdlet Stop-Proc definiert das HelpMessage Attributschlüsselwort 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

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

Unterstützen der Erweiterung von Wildcards

Um die Auswahl mehrerer Objekte zuzulassen, kann Ihr Cmdlet die System.Management.Automation.WildcardPattern- und System.Management.Automation.WildcardOptions- Klassen verwenden, um Die Unterstützung der Wildcarderweiterung für die Parametereingabe bereitzustellen. Beispiele für Wildcardmuster sind lsa*, *.txtund [a-c]*. Verwenden Sie das 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 die Unterstützung für Pfadeingaben ermöglichen kann, wenn die Auswahl mehrerer Objekte erforderlich ist. Ein gängiger Fall befindet sich im Dateisystem, in dem ein Benutzer alle Dateien sehen möchte, die sich im aktuellen Ordner befinden.

Sie sollten nur selten eine angepasste Implementierung für den Übereinstimmungsabgleich von Wildcardmustern benötigen. In diesem Fall sollte Ihr Cmdlet entweder die vollständige POSIX 1003.2, 3.13-Spezifikation für die Erweiterung von Wildcards oder die folgende vereinfachte Teilmenge unterstützen:

  • Fragezeichen (?). Entspricht einem beliebigen Zeichen an der angegebenen Position.
  • Sternchen (*). Gleicht null oder mehr Zeichen ab, die an der angegebenen Position beginnen.
  • Offene Klammer ([). Führt einen Musterklammerausdruck ein, der Zeichen oder einen Bereich von Zeichen enthalten kann. Wenn ein Bereich erforderlich ist, wird ein Bindestrich (-) verwendet, um den Bereich anzugeben.
  • Schließen sie eckige Klammer (]). Beendet einen Musterklammerausdruck.
  • Escapezeichen für Das Zurück-Anführungszeichen (`). Gibt an, dass das nächste Zeichen wörtlich genommen werden soll. Beachten Sie, dass beim Angeben des Zurück-Anführungszeichens aus der Befehlszeile (im Gegensatz zur programmgesteuerten Angabe) das Escapezeichen für das hintere Anführungszeichen zweimal angegeben werden muss.

Hinweis

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

Im folgenden Code wird gezeigt, wie Sie Die Optionen für Die Wildcard festlegen und das Zum Auflösen des Name-Parameters 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 mit dem definierten Platzhaltermuster übereinstimmt. Beachten Sie, dass das Cmdlet weiterhin den nächsten Prozessnamen erhält, wenn der Prozessname nicht mit dem Muster übereinstimmt.

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

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie unter StopProcessSample03 Sample.

Definieren von Objekttypen und Formatierungen

Windows PowerShell übergibt Informationen zwischen Cmdlets mithilfe von .NET-Objekten. Daher muss ein Cmdlet möglicherweise einen eigenen Typ definieren, oder das Cmdlet muss einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder zum 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 bei 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 bei Windows PowerShell registriert wurde, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Testen wir das Beispiel-Stop-Proc Cmdlet. Weitere Informationen zur Verwendung von Cmdlets über die Befehlszeile finden Sie in der Erste Schritte mit Windows PowerShell.

  • Starten Sie Windows PowerShell, und verwenden Sie Stop-Proc, 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

  • Nehmen Sie den folgenden Eintrag in der Befehlszeile vor. Da der Parameter Name obligatorisch ist, werden Sie dazu aufgefordert. Wenn Sie !? eingeben, wird der Hilfetext angezeigt, der dem Parameter zugeordnet ist.

    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

  • Machen Sie nun den folgenden Eintrag, 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

Siehe auch

  • Last updated on