Hinzufügen von Parametern, die Befehlszeileneingaben verarbeiten

Artikel
09/24/2021

Eine Eingabequelle für ein Cmdlet ist die Befehlszeile. In diesem Thema wird beschrieben, wie Sie dem Cmdlet einen Parameter hinzufügen Get-Proc (der unter Erstellen Ihres ersten Cmdletsbeschrieben wird), damit das Cmdlet Eingaben vom lokalen Computer auf der Grundlage expliziter Objekte verarbeiten kann, die an das Cmdlet übergeben werden. Das Get-Proc hier beschriebene Cmdlet ruft Prozesse basierend auf ihren Namen ab und zeigt dann Informationen zu den Prozessen an einer Eingabeaufforderung an.

Definieren der Cmdlet-Klasse

Der erste Schritt bei der Cmdlet-Erstellung ist die Cmdlet-Benennung und die Deklaration der .NET Framework Klasse, die das Cmdlet implementiert. Dieses Cmdlet ruft Prozessinformationen ab, sodass der hier ausgewählte Verbname "Get" lautet. (Fast jede Art von Cmdlet, das Informationen abrufen kann, kann Befehlszeileneingaben verarbeiten.) Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet Verb Names.

Hier ist die Klassendeklaration für das Get-Proc Cmdlet. Details zu dieser Definition finden Sie unter Erstellen Ihres ersten Cmdlets.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Deklarieren von Parametern

Mit einem Cmdlet-Parameter kann der Benutzer Eingaben für das Cmdlet bereitstellen. Im folgenden Beispiel Get-Proc sind und die Namen von Get-Member pipelined-Cmdlets und MemberType ein Parameter für das Get-Member Cmdlet. Der Parameter verfügt über das Argument "property".

PS> get-proc ; get-member -membertype-Eigenschaft

Um Parameter für ein Cmdlet zu deklarieren, müssen Sie zuerst die Eigenschaften definieren, die die Parameter darstellen. Im Get-Proc Cmdlet ist der einzige Parameter , der Name in diesem Fall den Namen des abzurufenden .NET Framework Prozessobjekts darstellt. Daher definiert die Cmdlet-Klasse eine Eigenschaft vom Typ string, um ein Array von Namen zu akzeptieren.

Hier ist die Parameterdeklaration für den Name Parameter des Get-Proc Cmdlets.

/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
  [Parameter(Position = 0)]
  [ValidateNotNullOrEmpty]
  public string[] Name
  {
    get { return processNames; }
    set { processNames = value; }
  }
  private string[] processNames;

  #endregion Parameters

<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Um die Windows PowerShell Runtime darüber zu informieren, dass diese Eigenschaft der Name Parameter ist, wird der Eigenschaftendefinition ein System.Management.Automation.Parameterattribute-Attribut hinzugefügt. Die grundlegende Syntax zum Deklarieren dieses Attributs ist [Parameter()] .

Hinweis

Ein Parameter muss explizit als öffentlich gekennzeichnet werden. Parameter, die nicht als öffentlicher Standardwert für intern markiert sind und von der Windows PowerShell Runtime nicht gefunden werden.

Dieses Cmdlet verwendet ein Array von Zeichenfolgen für den Name Parameter. Wenn möglich, sollte Ihr Cmdlet auch einen Parameter als Array definieren, da dies es dem Cmdlet ermöglicht, mehr als ein Element zu akzeptieren.

Zu beachtende Punkte zu Parameterdefinitionen

Vordefinierte Windows PowerShell Parameternamen und Datentypen sollten so weit wie möglich wiederverwendet werden, um sicherzustellen, dass Ihr Cmdlet mit Windows PowerShell Cmdlets kompatibel ist. Wenn beispielsweise alle Cmdlets den vordefinierten Id Parameternamen verwenden, um eine Ressource zu identifizieren, kann der Benutzer die Bedeutung des Parameters leicht verstehen, unabhängig davon, welches Cmdlet er verwendet. Im Grunde folgen Parameternamen den gleichen Regeln wie für Variablennamen in der Common Language Runtime (CLR). Weitere Informationen zur Parameterbenennung finden Sie unter Cmdlet-Parameternamen.
Windows PowerShell reserviert einige Parameternamen, um eine konsistente Benutzererfahrung zu gewährleisten. Verwenden Sie diese Parameternamen nicht: WhatIf , , , , , , , , Confirm und Verbose Debug Warn ErrorAction ErrorVariable OutVariable OutBuffer . Darüber hinaus sind die folgenden Aliase für diese Parameternamen reserviert: vb , , , , und db ea ev ov ob .
Name ist ein einfacher und allgemeiner Parametername, der für die Verwendung in Ihren Cmdlets empfohlen wird. Es ist besser, einen Parameternamen wie diesen auszuwählen als einen komplexen Namen, der für ein bestimmtes Cmdlet eindeutig und schwer zu merken ist.
Bei Parametern wird die Groß-/Kleinschreibung in Windows PowerShell nicht beachtet, obwohl die Groß-/Kleinschreibung von der Shell standardmäßig beibehalten wird. Die Empfindlichkeit der Argumente für die Kleinschreibung hängt vom Betrieb des Cmdlets ab. Argumente werden wie in der Befehlszeile angegeben an einen Parameter übergeben.
Beispiele für andere Parameterdeklarationen finden Sie unter Cmdlet-Parameter.

Deklarieren von Parametern als positional oder benannt

Ein Cmdlet muss jeden Parameter entweder als Positionsparameter oder als benannten Parameter festlegen. Beide Arten von Parametern akzeptieren einzelne Argumente, mehrere durch Kommas getrennte Argumente und boolesche Einstellungen. Ein boolescher Parameter, der auch als Switch bezeichnet wird, verarbeitet nur boolesche Einstellungen. Der Schalter wird verwendet, um das Vorhandensein des Parameters zu bestimmen. Der empfohlene Standardwert ist false .

Das Get-Proc Beispiel-Cmdlet definiert den Name Parameter als Positionsparameter mit Position. 0. Das bedeutet, dass das erste Argument, das der Benutzer in die Befehlszeile eingibt, automatisch für diesen Parameter eingefügt wird. Wenn Sie einen benannten Parameter definieren möchten, für den der Benutzer den Parameternamen über die Befehlszeile angeben muss, lassen Sie das Position Schlüsselwort aus der Attributdeklaration weg.

Hinweis

Sofern keine Parameter benannt werden müssen, wird empfohlen, die am häufigsten verwendeten Parameter so zu positionieren, dass Benutzer den Parameternamen nicht eingeben müssen.

Deklarieren von Parametern als obligatorisch oder optional

Ein Cmdlet muss jeden Parameter entweder als optionalen oder obligatorischen Parameter festlegen. Im Get-Proc Beispiel-Cmdlet wird der Name Parameter als optional definiert, da das Schlüsselwort Mandatory in der Attributdeklaration nicht festgelegt ist.

Unterstützen der Parametervalidierung

Das Get-Proc Beispiel-Cmdlet fügt dem Parameter das Eingabevalidierungsattribut System.Management.Automation.Validatenotnulloremptyattributehinzu, Name um die Überprüfung zu ermöglichen, dass die Eingabe weder noch leer null ist. Dieses Attribut ist eines von mehreren Validierungsattributen, die von Windows PowerShell bereitgestellt werden. Beispiele für andere Validierungsattribute finden Sie unter Validating Parameter Input.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

Überschreiben einer Eingabeverarbeitungsmethode

Wenn Ihr Cmdlet Befehlszeileneingaben verarbeiten soll, muss es die entsprechenden Eingabeverarbeitungsmethoden überschreiben. Die grundlegenden Eingabeverarbeitungsmethoden werden unter Creating Your First Cmdlet (Erstellen Ihres ersten Cmdlets)eingeführt.

Das Get-Proc Cmdlet überschreibt die System.Management.Automation.Cmdlet.ProcessRecord-Methode, um die Name vom Benutzer oder einem Skript bereitgestellte Parametereingabe zu verarbeiten. Diese Methode ruft die Prozesse für jeden angeforderten Prozessnamen oder alle prozesse ab, wenn kein Name angegeben wird. Beachten Sie, dass in System.Management.Automation.Cmdlet.ProcessRecordder Aufruf von System.Management.Automation.Cmdlet.WriteObject%28System.Object%2CSystem.Boolean%29 der Ausgabemechanismus zum Senden von Ausgabeobjekten an die Pipeline ist. Der zweite Parameter dieses Aufrufs enumerateCollection ist auf festgelegt, true um die Windows PowerShell Runtime zu informieren, das Ausgabearray von Prozessobjekten aufzuzählen und jeweils einen Prozess in die Befehlszeile zu schreiben.

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
    // Write the processes to the pipeline making them available
    // to the next cmdlet. The second argument of this call tells
    // PowerShell to enumerate the array, and send one process at a
    // time to the pipeline.
    WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    }
  }
}

Protected Overrides Sub ProcessRecord()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        Dim processes As Process()
        processes = Process.GetProcesses()
    End If

    '/ If process names are specified, write the processes to the
    '/ pipeline to display them or make them available to the next cmdlet.

    For Each name As String In processNames
        '/ The second parameter of this call tells PowerShell to enumerate the
        '/ array, and send one process at a time to the pipeline.
        WriteObject(Process.GetProcessesByName(name), True)
    Next

End Sub 'ProcessRecord

Codebeispiel

Den vollständigen C#-Beispielcode finden Sie unter GetProcessSample02-Beispiel.

Definieren von Objekttypen und Formatierung

Windows PowerShell übergibt Informationen mithilfe .NET Framework -Objekte zwischen Cmdlets. Folglich muss ein Cmdlet möglicherweise einen eigenen Typ definieren, oder ein 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 Formatierenvon .

Erstellen des Cmdlets

Nachdem Sie ein Cmdlet implementiert haben, müssen Sie es mithilfe eines Windows PowerShell Snap-Ins bei Windows PowerShell registrieren. 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 ist, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Es gibt zwei Möglichkeiten, den Code für das Beispiel-Cmdlet zu testen. Weitere Informationen zur Verwendung von Cmdlets über die Befehlszeile finden Sie unter Erste Schritte mit Windows PowerShell.

Verwenden Sie an der eingabeaufforderung Windows PowerShell folgenden Befehl, um den Internet Explorer Prozess mit dem Namen "IEXPLORE" aufzulisten.

get-proc -name iexplore

Die folgende Ausgabe wird angezeigt.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore

Verwenden Sie den folgenden Befehl, um die Internet Explorer, Outlook und Editor Prozesse mit den Namen "IEXPLORE", "OUTLOOK" und "NOTEPAD" aufzulisten. Wenn mehrere Prozesse vorhanden sind, werden alle angezeigt.

get-proc -name iexplore, outlook, notepad

Die folgende Ausgabe wird angezeigt.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----  ------   --   -----------
    732      21  24696    5000    138   2.25  2288   iexplore
    715      19  20556   14116    136   1.78  3860   iexplore
   3917      62  74096   58112    468 191.56  1848   OUTLOOK
     39       2   1024    3280     30   0.09  1444   notepad
     39       2   1024     356     30   0.08  3396   notepad