Dodawanie zestawu parametrów do polecenia cmdlet

2025-03-25

Informacje o zestawach parametrów

Program Windows PowerShell definiuje zestaw parametrów jako grupę parametrów, które działają razem. Grupując parametry polecenia cmdlet, można utworzyć pojedyncze polecenie cmdlet, które może zmienić jego funkcjonalność na podstawie grupy parametrów, które określa użytkownik.

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

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

Aby zilustrować ten ostatni punkt, to polecenie cmdlet Stop-Proc używa trzech zestawów parametrów: ProcessName, ProcessIdi 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ółdzielić inne parametry, ale polecenie cmdlet używa unikatowych parametrów ProcessName, ProcessIdi InputObject w celu określenia zestawu parametrów, które powinny być używane przez środowisko uruchomieniowe programu Windows PowerShell.

Deklarowanie klasy poleceń cmdlet

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

Uwaga

Aby uzyskać więcej informacji na temat zatwierdzonych nazw czasowników poleceń cmdlet, zobacz Cmdlet Verb Names.

Poniższy kod to definicja klasy dla tego polecenia cmdlet Stop-Proc.

[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 wymagane jako dane wejściowe do polecenia cmdlet (te parametry definiują również zestawy parametrów), a także Force parametr, który zarządza tym, co robi polecenie cmdlet i PassThru parametr, który określa, czy polecenie cmdlet wysyła obiekt wyjściowy za pośrednictwem potoku. Domyślnie to polecenie cmdlet nie przekazuje obiektu przez potok. Aby uzyskać więcej informacji na temat tych dwóch ostatnich parametrów, zobacz Creating a Cmdlet that Modifies the System.

Deklarowanie parametru name

Ten parametr wejściowy umożliwia użytkownikowi określenie nazw procesów do zatrzymania. Należy pamiętać, że atrybut ParameterSetName słowo kluczowe System.Management.Automation.ParameterAttribute określa ProcessName parametr ustawiony 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ż pamiętać, że alias "ProcessName" jest podawany do tego parametru.

Deklarowanie parametru id

Ten parametr wejściowy umożliwia użytkownikowi określenie identyfikatorów procesów do zatrzymania. Należy pamiętać, że atrybut ParameterSetName słowo kluczowe System.Management.Automation.ParameterAttribute określa zestaw parametrów ProcessId.

[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ż pamiętać, że alias "ProcessId" jest podany dla tego parametru.

Deklarowanie parametru InputObject

Ten parametr wejściowy umożliwia użytkownikowi określenie obiektu wejściowego zawierającego informacje o zatrzymaniu procesów. Należy pamiętać, że atrybut ParameterSetName słowo kluczowe System.Management.Automation.ParameterAttribute określa InputObject parametr ustawiony 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ż pamiętać, że ten parametr nie ma aliasu.

Deklarowanie parametrów w wielu zestawach parametrów

Chociaż dla każdego zestawu parametrów musi istnieć unikatowy parametr, parametry mogą należeć do więcej niż jednego zestawu parametrów. W takich przypadkach podaj udostępniony parametr System.Management.Automation.ParameterAttribute deklaracji atrybutu dla każdego zestawu, do którego należy parametr. Jeśli parametr znajduje się we wszystkich zestawach parametrów, wystarczy zadeklarować atrybut parametru raz i nie trzeba określać nazwy zestawu parametrów.

Zastępowanie metody przetwarzania wejściowego

Każde polecenie cmdlet musi zastąpić metodę przetwarzania danych wejściowych. Najczęściej będzie to metoda System.Management.Automation.Cmdlet.ProcessRecord. W tym poleceniu cmdlet jest zastępowana metoda System.Management.Automation.Cmdlet.ProcessRecord, dzięki czemu polecenie cmdlet może przetwarzać dowolną liczbę procesów. Zawiera instrukcję Select, która wywołuje inną metodę na podstawie określonego parametru.

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 instrukcję Select nie zostały opisane tutaj, ale w następnej sekcji można zobaczyć ich implementację w kompletnym przykładzie kodu.

Przykładowy kod

Aby uzyskać pełny przykładowy kod w języku C#, zobacz StopProcessSample04 Sample.

Definiowanie typów obiektów i formatowanie

Program Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym może być konieczne zdefiniowanie własnego typu polecenia cmdlet 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.

Kompilowanie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy zarejestrować je w programie Windows PowerShell za pomocą przystawki programu Windows PowerShell. Aby uzyskać więcej informacji na temat rejestrowania poleceń cmdlet, zobacz Jak rejestrować polecenia cmdlet, dostawcy i aplikacje hosta.

Testowanie polecenia cmdlet

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

Po uruchomieniu programu Windows PowerShell uruchom polecenie cmdlet Stop-Proc z parametrem ProcessId ustawionym, aby zatrzymać proces na podstawie jego identyfikatora. W takim przypadku polecenie cmdlet używa parametru ProcessId ustawionego w celu 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 uruchomieniu programu Windows PowerShell uruchom polecenie cmdlet Stop-Proc z parametrem InputObject ustawionym na zatrzymanie procesów w obiekcie Notatnika pobranym przez polecenie Get-Process.

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