Typy parametrów poleceń cmdlet

W tym temacie opisano różne typy parametrów, które można zadeklarować w poleceniach cmdlet. Parametry polecenia cmdlet mogą być pozycyjne, nazwane, wymagane, opcjonalne lub [switch] parametry.

Parametry pozycyjne i nazwane

Wszystkie parametry polecenia cmdlet są nazwane lub parametry pozycyjne. Nazwany parametr wymaga wpisania nazwy parametru i argumentu podczas wywoływania polecenia cmdlet. Parametr pozycyjny wymaga tylko wpisywania argumentów w kolejności względnej. Następnie system mapuje pierwszy nienazwany argument na pierwszy parametr pozycyjny. System mapuje drugi nienazwany argument na drugi nienazwany parametr itd. Domyślnie wszystkie parametry polecenia cmdlet mają nazwane parametry.

Aby zdefiniować nazwany parametr, pomiń słowo kluczowe Position w deklaracji atrybutu parametru, jak pokazano w poniższej deklaracji parametru.

[Parameter(ValueFromPipeline=true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Aby zdefiniować parametr pozycyjny, dodaj słowo kluczowe Position w deklaracji atrybutu Parametr, a następnie określ pozycję. W poniższym przykładzie parametr UserName jest zadeklarowany jako parametr pozycyjny z pozycją 0. Oznacza to, że pierwszy argument wywołania jest automatycznie powiązany z tym parametrem.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

Uwaga

Dobry projekt polecenia cmdlet zaleca zadeklarowanie najczęściej używanych parametrów jako parametrów pozycyjnych, aby użytkownik nie musiał wprowadzać nazwy parametru podczas uruchamiania polecenia cmdlet.

Parametry pozycyjne i nazwane akceptują pojedyncze argumenty lub wiele argumentów rozdzielonych przecinkami. Wiele argumentów jest dozwolonych tylko wtedy, gdy parametr akceptuje kolekcję, taką jak tablica ciągów. W tym samym poleceniu cmdlet można mieszać parametry pozycyjne i nazwane. W takim przypadku system najpierw pobiera nazwane argumenty, a następnie próbuje zamapować pozostałe nienazwane argumenty na parametry pozycyjne.

Poniższe polecenia pokazują różne sposoby określania pojedynczych i wielu argumentów dla parametrów polecenia cmdlet Get-Command. Zwróć uwagę, że w dwóch ostatnich próbkach nie trzeba określać -Name, ponieważ parametr nazwa jest zdefiniowany jako parametr pozycyjny.

Get-Command -Name Get-Service
Get-Command -Name Get-Service,Set-Service
Get-Command Get-Service
Get-Command Get-Service,Set-Service

Obowiązkowe i opcjonalne parametry

Można również zdefiniować parametry polecenia cmdlet jako obowiązkowe lub opcjonalne parametry. (Należy określić obowiązkowy parametr, zanim środowisko uruchomieniowe programu PowerShell wywołuje polecenie cmdlet). Domyślnie parametry są definiowane jako opcjonalne.

Aby zdefiniować obowiązkowy parametr, dodaj słowo kluczowe Mandatory w deklaracji atrybutu Parametr i ustaw go na true, jak pokazano w poniższej deklaracji parametru.

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

Aby zdefiniować opcjonalny parametr, pomiń słowo kluczowe Mandatory w deklaracji atrybutu Parametr, jak pokazano w poniższej deklaracji parametru.

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[switch] Parametry

Program PowerShell udostępnia typ System.Management.Automation.SwitchPara meter, który umożliwia zdefiniowanie parametru, którego wartość domyślna false, chyba że parametr jest określony podczas wywoływanego polecenia cmdlet. Jeśli to możliwe, użyj [switch] parametrów zamiast parametrów logicznych.

Rozważmy poniższy przykład. Wiele poleceń cmdlet programu PowerShell zwraca dane wyjściowe. Jednak te polecenia cmdlet mają PassThru[switch] parametr, który zastępuje zachowanie domyślne. W przypadku użycia parametru PassThru polecenie cmdlet zwraca obiekty wyjściowe do potoku.

W poniższym przykładzie pokazano, jak zdefiniować [switch] parametr:

[Parameter()]
public SwitchParameter GoodBye
{
  get { return goodbye; }
  set { goodbye = value; }
}
private bool goodbye;

Aby polecenie cmdlet działało na parametrze po jego określeniu, użyj następującej struktury w jednej z metod przetwarzania wejściowego.

protected override void ProcessRecord()
{
  WriteObject("Switch parameter test: " + userName + ".");
  if (goodbye)
  {
    WriteObject(" Goodbye!");
  }
} // End ProcessRecord

Domyślnie [switch] parametry są wykluczane z parametrów pozycyjnych. można zastąpić to atrybutem parametru, ale może to mylić użytkowników.

Parametry projektu [switch] tak, aby użycie parametru zmienia domyślne zachowanie polecenia w mniej typowy lub bardziej skomplikowany tryb. Najprostszym zachowaniem polecenia powinno być zachowanie domyślne, które nie wymaga użycia parametrów [switch] . Na podstawie zachowania kontrolowanego [switch] przez parametr na wartości parametru, a nie jego obecności.

Istnieje kilka sposobów testowania obecności parametru [switch] :

• MyInvocation.BoundParameters zawiera nazwę parametru [switch] jako klucz
• PSCmdlet.ParameterSetName [switch] gdy parametr definiuje unikatowy zestaw parametrów

Na przykład można podać jawną wartość przełącznika przy użyciu -MySwitch:$false lub przeplatania. Jeśli testujesz tylko obecność parametru, polecenie zachowuje się tak, jakby wartość przełącznika jest $true zamiast $false.

Zobacz też

Writing a Windows PowerShell Cmdlet