Hinzufügen von Parametersätzen zu einem Cmdlet

Artikel
09/27/2021

Wissenswertes zu Parametersätzen

Windows PowerShell definiert einen Parametersatz als Eine Gruppe von Parametern, die zusammenarbeiten. Indem Sie die Parameter eines Cmdlets gruppieren, können Sie ein einzelnes Cmdlet erstellen, das seine Funktionalität basierend auf der vom Benutzer angegebenen Gruppe von Parametern ändern kann.

Ein Beispiel für ein Cmdlet, das zwei Parametersätze verwendet, um verschiedene Funktionen zu definieren, ist das Get-EventLog Cmdlet, das von Windows PowerShell bereitgestellt wird. Dieses Cmdlet gibt unterschiedliche Informationen zurück, wenn der Benutzer den List Parameter oder angibt. LogName Wenn der LogName Parameter angegeben wird, gibt das Cmdlet Informationen zu den Ereignissen in einem bestimmten Ereignisprotokoll zurück. Wenn der List Parameter angegeben wird, gibt das Cmdlet Informationen zu den Protokolldateien selbst zurück (nicht die darin enthaltenen Ereignisinformationen). In diesem Fall identifizieren die List Parameter und zwei separate LogName Parametersätze.

Zwei wichtige Punkte zu Parametersätzen sind, dass die Windows PowerShell Runtime nur einen Parametersatz für eine bestimmte Eingabe verwendet und dass jeder Parametersatz mindestens einen Parameter aufweisen muss, der für diesen Parametersatz eindeutig ist.

Um diesen letzten Punkt zu veranschaulichen, verwendet dieses Stop-Proc Cmdlet drei Parametersätze: ProcessName ProcessId , und InputObject . Jeder dieser Parametersätze verfügt über einen Parameter, der sich nicht in den anderen Parametersätzen befindet. Die Parametersätze können andere Parameter gemeinsam verwenden, aber das Cmdlet verwendet die eindeutigen Parameter ProcessName , und , um zu ProcessId InputObject identifizieren, welche Parametermenge von der Windows PowerShell Runtime verwendet werden soll.

Deklarieren der Cmdlet-Klasse

Der erste Schritt bei der Cmdlet-Erstellung besteht immer darin, das Cmdlet zu benennen und die .NET-Klasse zu deklarieren, die das Cmdlet implementiert. Für dieses Cmdlet wird das Lebenszyklusverb "Stop" verwendet, da das Cmdlet Systemprozesse beendet. Der Nomenname "Proc" wird verwendet, da das Cmdlet für Prozesse funktioniert. Beachten Sie in der folgenden Deklaration, dass das Cmdlet-Verb und der Nomenname im Namen der Cmdlet-Klasse widergespiegelt werden.

Hinweis

Weitere Informationen zu genehmigten Cmdlet-Verbnamen finden Sie unter Cmdlet Verb Names.

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

[Cmdlet(VerbsLifecycle.Stop, "Proc",
        DefaultParameterSetName = "ProcessId",
        SupportsShouldProcess = true)]
public class StopProcCommand : PSCmdlet

<Cmdlet(VerbsLifecycle.Stop, "Proc", DefaultParameterSetName:="ProcessId", _
SupportsShouldProcess:=True)> _
Public Class StopProcCommand
    Inherits PSCmdlet

Deklarieren der Parameter des Cmdlets

Dieses Cmdlet definiert drei Parameter, die als Eingabe für das Cmdlet erforderlich sind (diese Parameter definieren auch die Parametersätze), sowie einen Force Parameter, der verwaltet, was das Cmdlet tut, und einen PassThru Parameter, der bestimmt, ob das Cmdlet ein Ausgabeobjekt über die Pipeline sendet. Standardmäßig übergibt dieses Cmdlet kein Objekt über die Pipeline. Weitere Informationen zu diesen beiden letzten Parametern finden Sie unter Erstellen eines Cmdlets, das das System ändert.

Deklarieren des Namensparameters

Mit diesem Eingabeparameter kann der Benutzer die Namen der prozesse angeben, die beendet werden sollen. Beachten Sie, dass das ParameterSetName Attributschlüsselwort des Attributs System.Management.Automation.Parameterattribute den ProcessName Parametersatz für diesen Parameter angibt.

[Parameter(
   Position = 0,
   ParameterSetName = "ProcessName",
   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;

<Parameter(Position:=0, ParameterSetName:="ProcessName", _
Mandatory:=True, _
ValueFromPipeline:=True, ValueFromPipelineByPropertyName:=True, _
HelpMessage:="The name of one or more processes to stop. " & _
    "Wildcards are permitted."), [Alias]("ProcessName")> _
Public Property Name() As String()
    Get
        Return processNames
    End Get
    Set(ByVal value As String())
        processNames = value
    End Set
End Property

Private processNames() As String

Beachten Sie auch, dass dieser Parameter den Alias "ProcessName" erhält.

Deklarieren des ID-Parameters

Mit diesem Eingabeparameter kann der Benutzer die Bezeichner der prozesse angeben, die beendet werden sollen. Beachten Sie, dass das ParameterSetName Attributschlüsselwort des Attributs System.Management.Automation.Parameterattribute den ProcessId Parametersatz angibt.

[Parameter(
           ParameterSetName = "ProcessId",
           Mandatory = true,
           ValueFromPipelineByPropertyName = true,
           ValueFromPipeline = true
)]
[Alias("ProcessId")]
public int[] Id
{
  get { return processIds; }
  set { processIds = value; }
}
private int[] processIds;

<Parameter(ParameterSetName:="ProcessId", _
Mandatory:=True, _
ValueFromPipelineByPropertyName:=True, _
ValueFromPipeline:=True), [Alias]("ProcessId")> _
Public Property Id() As Integer()
    Get
        Return processIds
    End Get
    Set(ByVal value As Integer())
        processIds = value
    End Set
End Property
Private processIds() As Integer

Beachten Sie auch, dass dieser Parameter den Alias "ProcessId" erhält.

Deklarieren des InputObject-Parameters

Mit diesem Eingabeparameter kann der Benutzer ein Eingabeobjekt angeben, das Informationen zu den zu stoppenden Prozessen enthält. Beachten Sie, dass das ParameterSetName Attributschlüsselwort des Attributs System.Management.Automation.Parameterattribute den InputObject Parametersatz für diesen Parameter angibt.

[Parameter(
           ParameterSetName = "InputObject",
           Mandatory = true,
           ValueFromPipeline = true)]
public Process[] InputObject
{
  get { return inputObject; }
  set { inputObject = value; }
}
private Process[] inputObject;

<Parameter(ParameterSetName:="InputObject", _
Mandatory:=True, ValueFromPipeline:=True)> _
Public Property InputObject() As Process()
    Get
        Return myInputObject
    End Get
    Set(ByVal value As Process())
        myInputObject = value
    End Set
End Property
Private myInputObject() As Process

Beachten Sie auch, dass dieser Parameter keinen Alias hat.

Deklarieren von Parametern in mehreren Parametersätzen

Obwohl es einen eindeutigen Parameter für jeden Parametersatz geben muss, können Parameter zu mehr als einem Parametersatz gehören. Geben Sie in diesen Fällen dem freigegebenen Parameter eine System.Management.Automation.Parameterattribute-Attributdeklaration für jeden Satz, zu dem der Parameter gehört. Wenn sich ein Parameter in allen Parametersätzen befindet, müssen Sie das Parameterattribut nur einmal deklarieren und müssen nicht den Namen des Parametersatzes angeben.

Überschreiben einer Eingabeverarbeitungsmethode

Jedes Cmdlet muss eine Eingabeverarbeitungsmethode überschreiben. In den meisten Fällen ist dies die System.Management.Automation.Cmdlet.ProcessRecord-Methode. In diesem Cmdlet wird die System.Management.Automation.Cmdlet.ProcessRecord-Methode überschrieben, sodass das Cmdlet eine beliebige Anzahl von Prozessen verarbeiten kann. Sie enthält eine Select-Anweisung, die eine andere Methode aufruft, basierend darauf, welchen Parametersatz der Benutzer angegeben hat.

protected override void ProcessRecord()
{
  switch (ParameterSetName)
  {
    case "ProcessName":
         ProcessByName();
         break;

    case "ProcessId":
         ProcessById();
         break;

    case "InputObject":
         foreach (Process process in inputObject)
         {
           SafeStopProcess(process);
         }
         break;

    default:
         throw new ArgumentException("Bad ParameterSet Name");
  } // switch (ParameterSetName...
} // ProcessRecord

Protected Overrides Sub ProcessRecord()
    Select Case ParameterSetName
        Case "ProcessName"
            ProcessByName()

        Case "ProcessId"
            ProcessById()

        Case "InputObject"
            Dim process As Process
            For Each process In myInputObject
                SafeStopProcess(process)
            Next process

        Case Else
            Throw New ArgumentException("Bad ParameterSet Name")
    End Select

End Sub 'ProcessRecord ' ProcessRecord

Die hilfsmethoden, die von der Select-Anweisung aufgerufen werden, werden hier nicht beschrieben, aber Sie sehen ihre Implementierung im vollständigen Codebeispiel im nächsten Abschnitt.

Codebeispiel

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

Definieren von Objekttypen und Formatierung

Windows PowerShell übergibt Informationen mithilfe von .NET-Objekten zwischen Cmdlets. Folglich 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 Formatierenvon .

Erstellen des Cmdlets

Nach der Implementierung eines Cmdlets müssen Sie es mit Windows PowerShell über ein Windows PowerShell Snap-In 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 wurde, testen Sie es, indem Sie es in der Befehlszeile ausführen. Hier sind einige Tests, die zeigen, wie die ProcessId Parameter und verwendet werden InputObject können, um ihre Parametersätze zu testen, um einen Prozess zu beenden.

Wenn Windows PowerShell gestartet wurde, führen Sie das cmdlet Stop-Proc aus, wobei der ProcessId Parameter festgelegt ist, um einen Prozess basierend auf seinem Bezeichner zu beenden. In diesem Fall verwendet das Cmdlet den ProcessId parameter set, um den Prozess zu beenden.
```
PS> stop-proc -Id 444
Confirm
Are you sure you want to perform this action?
Performing operation "stop-proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
```

Wenn Windows PowerShell gestartet wurde, führen Sie das cmdlet Stop-Proc aus, wobei der InputObject Parameter festgelegt ist, um Prozesse für das vom Befehl abgerufene Editor Objekt zu Get-Process beenden.

PS> get-process notepad | stop-proc
Confirm
Are you sure you want to perform this action?
Performing operation "stop-proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N