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ć parametry pozyacyjne, nazwane, wymagane, opcjonalne lub przełącznika.

Parametry pozyacyjne i nazwane

Wszystkie parametry polecenia cmdlet to parametry nazwane lub pozyacyjne. Nazwany parametr wymaga wpisania nazwy parametru i argumentu podczas wywoływania polecenia cmdlet. Parametr pozycyjnego wymaga tylko wpisania argumentów w kolejności względnej. Następnie system mapuje pierwszy nienazwane argument na pierwszy parametr pozytowy. System mapuje drugi nienazwane argument na drugi parametr bez nazwy i tak dalej. Domyślnie wszystkie parametry polecenia cmdlet są nazwane parametry.

Aby zdefiniować nazwany parametr, pomiń słowo kluczowe w Position 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 pozytowy, dodaj słowo kluczowe Position w deklaracji atrybutu parametru, a następnie określ pozycję. W poniższym przykładzie UserName parametr jest zadeklarowany jako parametr pozytowy z pozycją 0. Oznacza to, że pierwszy argument wywołania zostanie 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, aby najczęściej używane parametry były deklarowane jako parametry pozyacyjne, dzięki czemu użytkownik nie musi 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 polecenia cmdlet można mieszać parametry pozyacyjne i nazwane. W takim przypadku system najpierw pobiera nazwane argumenty, a następnie próbuje zamapować pozostałe nienazwane argumenty na parametry pozycyjne.

Następujące polecenia pokazują różne sposoby określania pojedynczych i wielu argumentów dla parametrów Get-Command polecenia cmdlet. Zwróć uwagę, że w dwóch ostatnich przykładach parametr -name nie musi być określony, ponieważ parametr jest zdefiniowany Name jako parametr pozytowy.

Get-Command -Name get-service
Get-Command -Name get-service,set-service
Get-Command get-service
Get-Command get-service,set-service

Parametry obowiązkowe i opcjonalne

Parametry polecenia cmdlet można również zdefiniować jako parametry obowiązkowe lub opcjonalne. (Obowiązkowy parametr należy określić, zanim środowisko Windows PowerShell uruchomieniowe wywoła polecenie cmdlet. Domyślnie parametry są zdefiniowane jako opcjonalne.

Aby zdefiniować obowiązkowy parametr, dodaj słowo kluczowe w deklaracji atrybutu parametru i ustaw go na wartość , jak Mandatory true 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 w Mandatory deklaracji atrybutu parametru, jak pokazano w poniższej deklaracji parametru.

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

Parametry przełącznika

Windows PowerShell typ System.Management.Automation.SwitchParameter, który umożliwia zdefiniowanie parametru, którego wartość jest automatycznie ustawiana na , jeśli parametr nie zostanie określony podczas wywoływania false polecenia cmdlet. Jeśli to możliwe, używaj parametrów przełącznika w miejsce parametrów logicznych.

Rozważmy następujący przykład. Domyślnie kilka Windows PowerShell cmdlet nie przekazywać obiektu wyjściowego do potoku. Jednak te polecenia cmdlet mają PassThru parametr przełącznika, który zastępuje zachowanie domyślne. Jeśli parametr jest określony podczas wywoływania tych PassThru cmdlet, polecenie cmdlet zwraca obiekt wyjściowy do potoku.

Jeśli potrzebujesz, aby parametr miał wartość domyślną , gdy parametr nie jest określony w wywołaniu, rozważ odwrócenie true odczucie parametru. Na przykład zamiast ustawiać atrybut parametru na wartość logiczną , zadeklaruj właściwość jako true typ System.Management.Automation.SwitchParameter, a następnie ustaw wartość domyślną parametru na false .

Aby zdefiniować parametr przełącznika, zadeklaruj właściwość jako typ System.Management.Automation.SwitchParameter, jak pokazano w poniższym przykładzie.

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

Aby polecenie cmdlet działało na parametrze , gdy jest określony, użyj następującej struktury w ramach jednej z metod przetwarzania danych wejściowych.

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

Zobacz też

Pisanie polecenia cmdlet programu Windows PowerShell