Zestawy parametrów polecenia cmdlet

Program PowerShell używa zestawów parametrów, aby umożliwić pisanie pojedynczego polecenia cmdlet, które może wykonać różne akcje dla różnych scenariuszy. Zestawy parametrów umożliwiają uwidocznić użytkownikowi różne parametry. Aby zwrócić różne informacje na podstawie parametrów określonych przez użytkownika.

Przykłady zestawów parametrów

Na przykład polecenie cmdlet programu PowerShell zwraca różne informacje w zależności od tego, czy Get-EventLog użytkownik określa parametr List, czy LogName. Jeśli określono parametr List, polecenie cmdlet zwraca informacje o samych plikach dziennika, ale nie o zawartych w nich informacjach o zdarzeniach. Jeśli określono parametr LogName, polecenie cmdlet zwraca informacje o zdarzeniach w określonym dzienniku zdarzeń. Parametry List i LogName identyfikują dwa oddzielne zestawy parametrów.

Unikatowy parametr

Każdy zestaw parametrów musi mieć unikatowy parametr używany przez środowisko uruchomieniowe programu PowerShell do udostępnienia odpowiedniego zestawu parametrów. Jeśli to możliwe, unikatowy parametr powinien być parametrem obowiązkowym. Jeśli parametr jest obowiązkowy, użytkownik musi określić parametr, a środowisko uruchomieniowe programu PowerShell używa tego parametru do identyfikowania zestawu parametrów. Unikatowy parametr nie może być obowiązkowy, jeśli polecenie cmdlet zostało zaprojektowane do uruchamiania bez określania żadnych parametrów.

Wiele zestawów parametrów

Na poniższej ilustracji w lewej kolumnie przedstawiono trzy prawidłowe zestawy parametrów. Parametr A jest unikatowy dla pierwszego zestawu parametrów, parametr B jest unikatowy dla drugiego zestawu parametrów, a parametr C jest unikatowy dla trzeciego zestawu parametrów. W prawej kolumnie zestawy parametrów nie mają unikatowego parametru.

Wymagania dotyczące zestawu parametrów

Poniższe wymagania dotyczą wszystkich zestawów parametrów.

• Każdy zestaw parametrów musi mieć co najmniej jeden unikatowy parametr. Jeśli to możliwe, należy wprowadzić ten parametr jako obowiązkowy.

• Zestaw parametrów, który zawiera wiele parametrów pozytywnych, musi definiować unikatowe pozycje dla każdego parametru. Żadne dwa parametry pozyacyjne nie mogą określić tej samej pozycji.

• Tylko jeden parametr w zestawie może zadeklarować słowo kluczowe ValueFromPipeline z wartością true . Wiele parametrów może definiować ValueFromPipelineByPropertyName słowo kluczowe o wartości true .

• Jeśli dla parametru nie określono żadnego zestawu parametrów, parametr należy do wszystkich zestawów parametrów.

Uwaga

W przypadku polecenia cmdlet lub funkcji istnieje limit 32 zestawów parametrów.

Domyślne zestawy parametrów

Jeśli zdefiniowano wiele zestawów parametrów, można użyć słowa kluczowego atrybutu DefaultParameterSetName polecenia cmdlet w celu określenia domyślnego zestawu parametrów. Program PowerShell używa domyślnego zestawu parametrów, jeśli nie może określić zestawu parametrów do użycia na podstawie informacji podanych przez polecenie . Aby uzyskać więcej informacji na temat atrybutu polecenia cmdlet, zobacz Deklaracja atrybutu polecenia cmdlet.

Deklarowanie zestawów parametrów

Aby utworzyć zestaw parametrów, należy określić słowo kluczowe podczas deklarowania atrybutu Parameter dla każdego parametru ParameterSetName w zestawie parametrów. W przypadku parametrów należących do wielu zestawów parametrów dodaj atrybut Parametr dla każdego zestawu parametrów. Ten atrybut umożliwia definiowanie parametru w różny sposób dla każdego zestawu parametrów. Na przykład można zdefiniować parametr jako obowiązkowy w jednym zestawie i opcjonalny w innym. Jednak każdy zestaw parametrów musi zawierać jeden unikatowy parametr. Aby uzyskać więcej informacji, zobacz Deklaracja atrybutu parametru.

W poniższym przykładzie parametr UserName jest unikatowym parametrem zestawu parametrów, a parametr ComputerName jest unikatowym Test01 parametrem Test02 zestawu parametrów. Parametr SharedParam należy do obu zestawów i jest obowiązkowy dla Test01 zestawu parametrów, ale opcjonalny dla Test02 zestawu parametrów.

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test01")]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[Parameter(Position = 0, Mandatory = true, ParameterSetName = "Test02")]
public string ComputerName
{
  get { return computerName; }
  set { computerName = value; }
}
private string computerName;

[Parameter(Mandatory= true, ParameterSetName = "Test01")]
[Parameter(ParameterSetName = "Test02")]
public string SharedParam
{
    get { return sharedParam; }
    set { sharedParam = value; }
}
private string sharedParam;