Dodawanie zestawu parametrów do polecenia cmdlet

Artykuł
09/27/2021

Co należy wiedzieć o zestawach parametrów

Windows PowerShell definiuje zestaw parametrów jako grupę parametrów, które działają razem. Grupując parametry polecenia cmdlet, można utworzyć jedno polecenie cmdlet, które może zmienić jego funkcjonalność w oparciu o grupę parametrów określaną przez użytkownika.

Przykładem polecenia cmdlet, które używa dwóch zestawów parametrów do definiowania różnych funkcji, jest polecenie cmdlet udostępniane przez Get-EventLog Windows PowerShell. To polecenie cmdlet zwraca różne informacje, gdy użytkownik określa List parametr LogName lub . Jeśli parametr LogName jest określony, polecenie cmdlet zwraca informacje o zdarzeniach w danym dzienniku zdarzeń. Jeśli parametr jest określony, polecenie cmdlet zwraca informacje o samych plikach dziennika (a nie informacje o List zdarzeniu, które zawierają). W tym przypadku parametry List i identyfikują dwa oddzielne LogName zestawy parametrów.

Dwie ważne rzeczy, o których należy pamiętać o zestawach parametrów, to to, że środowisko uruchomieniowe programu Windows PowerShell używa tylko jednego zestawu parametrów dla określonego wejścia i że każdy zestaw parametrów musi mieć co najmniej jeden parametr, który jest unikatowy dla tego zestawu parametrów.

Aby zilustrować ostatni punkt, to Stop-Proc cmdlet używa trzech zestawów parametrów: ProcessName ProcessId , i InputObject . Każdy z tych zestawów parametrów ma jeden parametr, który nie znajduje się w innych zestawach parametrów. Zestawy parametrów mogą współużytkować inne parametry, ale polecenie cmdlet używa unikatowych parametrów , , i do identyfikowania zestawu parametrów, które powinny ProcessName ProcessId Windows PowerShell InputObject uruchomieniowe.

Deklarowanie klasy polecenia cmdlet

Pierwszym krokiem podczas tworzenia polecenia cmdlet jest zawsze nazewnictwo polecenia cmdlet i deklarowanie klasy .NET, która implementuje polecenie cmdlet. W przypadku tego polecenia cmdlet czasownik cyklu życia "Stop" jest używany, ponieważ polecenie cmdlet zatrzymuje procesy systemowe. Nazwa rzeczownika "Proc" jest używana, ponieważ polecenie cmdlet działa w procesach. W poniższej deklaracji należy pamiętać, że czasownik polecenia cmdlet i nazwa rzeczownika są odzwierciedlane w nazwie klasy polecenia cmdlet.

Uwaga

Aby uzyskać więcej informacji na temat zatwierdzonych nazw czasowników polecenia cmdlet, zobacz Nazwy czasowników polecenia cmdlet.

Poniższy kod jest definicją klasy dla tego 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

Deklarowanie parametrów polecenia cmdlet

To polecenie cmdlet definiuje trzy parametry potrzebne jako dane wejściowe polecenia cmdlet (te parametry również definiują zestawy parametrów), a także parametr, który zarządza działaniami polecenia cmdlet, oraz parametr, który określa, czy polecenie cmdlet wysyła obiekt wyjściowy za pośrednictwem Force PassThru potoku. Domyślnie to polecenie cmdlet nie przechodzi przez potok obiektu. Aby uzyskać więcej informacji na temat tych dwóch ostatnich parametrów, zobacz Tworzenie polecenia cmdlet modyfikujące system.

Deklarowanie parametru Name

Ten parametr wejściowy umożliwia użytkownikowi określenie nazw procesów, które mają zostać zatrzymane. Należy pamiętać, ParameterSetName że słowo kluczowe atrybutu atrybutu System.Management.Automation.Parameterattribute określa ProcessName zestaw parametrów dla tego parametru.

[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

Należy również zauważyć, że alias "ProcessName" jest podany dla tego parametru.

Deklarowanie parametru Id

Ten parametr wejściowy umożliwia użytkownikowi określenie identyfikatorów procesów, które mają zostać zatrzymane. Należy pamiętać, ParameterSetName że słowo kluczowe atrybutu System.Management.Automation.Parameterattribute określa ProcessId zestaw parametrów.

[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

Należy również zauważyć, że alias "ProcessId" jest podany dla tego parametru.

Deklarowanie parametru InputObject

Ten parametr wejściowy umożliwia użytkownikowi określenie obiektu wejściowego, który zawiera informacje o procesach, które mają zostać zatrzymane. Należy pamiętać, ParameterSetName że słowo kluczowe atrybutu atrybutu System.Management.Automation.Parameterattribute określa InputObject zestaw parametrów dla tego parametru.

[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

Należy również zauważyć, że ten parametr nie ma aliasu.

Deklarowanie parametrów w wielu zestawach parametrów

Mimo że dla każdego zestawu parametrów musi być unikatowy parametr, parametry mogą należeć do więcej niż jednego zestawu parametrów. W takich przypadkach nadaj parametrowi udostępnionego deklarację atrybutu System.Management.Automation.Parameterattribute dla każdego zestawu, do którego należy parametr. Jeśli parametr znajduje się we wszystkich zestawach parametrów, wystarczy zadeklarować atrybut parametru tylko raz i nie trzeba określać nazwy zestawu parametrów.

Zastępowanie metody przetwarzania danych wejściowych

Każde polecenie cmdlet musi zastąpić metodę przetwarzania danych wejściowych. Najczęściej jest to metoda System.Management.Automation.Cmdlet.ProcessRecord. W tym cmdlet metoda System.Management.Automation.Cmdlet.ProcessRecord jest zastępowana, dzięki czemu polecenie cmdlet może przetwarzać dowolną liczbę procesów. Zawiera on instrukcje Select, które wywołuje inną metodę na podstawie zestawu parametrów określonego przez użytkownika.

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

Metody pomocnika wywoływane przez instrukcji Select nie zostały tutaj opisane, ale ich implementację można zobaczyć w kompletnym przykładzie kodu w następnej sekcji.

Przykład kodu

Aby uzyskać kompletny przykładowy kod w języku C#, zobacz StopProcessSample04 Sample (Przykład StopProcessSample04).

Definiowanie typów obiektów i formatowania

Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym polecenie cmdlet może wymagać zdefiniowania własnego typu lub może być konieczne rozszerzenie istniejącego typu dostarczonego przez inne polecenie cmdlet. Aby uzyskać więcej informacji na temat definiowania nowych typów lub rozszerzania istniejących typów, zobacz Rozszerzanie typów obiektów i formatowanie.

Tworzenie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy zarejestrować je w Windows PowerShell za pośrednictwem Windows PowerShell przystawki. Aby uzyskać więcej informacji na temat rejestrowania cmdlet, zobacz Jak rejestrować polecenia cmdlet,dostawców i aplikacje hosta .

Testowanie polecenia cmdlet

Po zarejestrowaniu polecenia cmdlet w Windows PowerShell, przetestuj je, uruchamiając je w wierszu polecenia. Poniżej znajdują się testy, które pokazują, jak parametry i mogą służyć do testowania zestawów parametrów w ProcessId InputObject celu zatrzymania procesu.

Po Windows PowerShell uruchom polecenie cmdlet Stop-Proc z parametrem ustawionym, aby zatrzymać proces ProcessId na podstawie jego identyfikatora. W takim przypadku polecenie cmdlet używa ProcessId zestawu parametrów do zatrzymania procesu.
```
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
```

Po Windows PowerShell uruchom polecenie cmdlet Stop-Proc z parametrem ustawionym w celu zatrzymania procesów na obiekcie InputObject Notatnik pobranym przez Get-Process polecenie .

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