Typy parametrów poleceń cmdletTypes of Cmdlet Parameters

W tym temacie opisano różne typy parametrów, które można zadeklarować w poleceniach cmdlet.This topic describes the different types of parameters that you can declare in cmdlets. Parametry polecenia cmdlet mogą mieć parametry pozycyjne, nazwane, wymagane, opcjonalne lub Switch.Cmdlet parameters can be positional, named, required, optional, or switch parameters.

Parametry pozycyjne i nazwanePositional and Named Parameters

Wszystkie parametry poleceń cmdlet są nazwane lub parametry pozycyjne.All cmdlet parameters are either named or positional parameters. Nazwany parametr wymaga wpisania nazwy parametru i argumentu podczas wywoływania polecenia cmdlet.A named parameter requires that you type the parameter name and argument when calling the cmdlet. Parametr pozycyjny wymaga tylko wpisania argumentów w kolejności względnej.A positional parameter requires only that you type the arguments in relative order. System następnie mapuje pierwszy nienazwany argument na pierwszy parametr pozycyjny.The system then maps the first unnamed argument to the first positional parameter. System mapuje drugi nienazwany argument do drugiego nienazwanego parametru i tak dalej.The system maps the second unnamed argument to the second unnamed parameter, and so on. Domyślnie wszystkie parametry poleceń cmdlet są nazwanymi parametrami.By default, all cmdlet parameters are named parameters.

Aby zdefiniować nazwany parametr, Pomiń Position słowo kluczowe w deklaracji atrybutu parametru , jak pokazano w następującej deklaracji parametru.To define a named parameter, omit the Position keyword in the Parameter attribute declaration, as shown in the following parameter declaration.

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

Aby zdefiniować parametr pozycyjny, Dodaj Position słowo kluczowe w deklaracji atrybutu parametru, a następnie określ pozycję.To define a positional parameter, add the Position keyword in the Parameter attribute declaration, and then specify a position. W poniższym przykładzie UserName parametr jest zadeklarowany jako parametr pozycyjny z pozycją 0.In the following sample, the UserName parameter is declared as a positional parameter with position 0. Oznacza to, że pierwszy argument wywołania zostanie automatycznie powiązany z tym parametrem.This means that the first argument of the call will be automatically bound to this parameter.

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

Uwaga

Dobrym projektem poleceń cmdlet zaleca się, aby najczęściej używane parametry były zadeklarowane jako parametry pozycyjne, aby użytkownik nie musiał wprowadzać nazwy parametru po uruchomieniu polecenia cmdlet.Good cmdlet design recommends that the most-used parameters be declared as positional parameters so that the user does not have to enter the parameter name when the cmdlet is run.

Parametry pozycyjne i nazwane akceptują pojedyncze argumenty lub wiele argumentów oddzielonych przecinkami.Positional and named parameters accept single arguments or multiple arguments separated by commas. Wiele argumentów jest dozwolonych tylko wtedy, gdy parametr akceptuje kolekcję, na przykład tablicę ciągów.Multiple arguments are allowed only if the parameter accepts a collection such as an array of strings. Możesz mieszać parametry pozycyjne i nazwane w tym samym poleceniu cmdlet.You may mix positional and named parameters in the same cmdlet. W tym przypadku system pobiera nazwane argumenty jako pierwsze, a następnie próbuje zmapować pozostałe nienazwane argumenty do parametrów pozycyjnych.In this case, the system retrieves the named arguments first, and then attempts to map the remaining unnamed arguments to the positional parameters.

Poniższe polecenia pokazują różne sposoby określania jednego i wielu argumentów parametrów Get-Command polecenia cmdlet.The following commands show the different ways in which you can specify single and multiple arguments for the parameters of the Get-Command cmdlet. Należy zauważyć, że w ciągu ostatnich dwóch próbek nie trzeba określać nazwy , ponieważ Name parametr jest zdefiniowany jako parametr pozycyjny.Notice that in the last two samples, -name does not need to be specified because the Name parameter is defined as a positional parameter.

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 opcjonalneMandatory and Optional Parameters

Parametry poleceń cmdlet można także definiować jako parametry obowiązkowe lub opcjonalne.You can also define cmdlet parameters as mandatory or optional parameters. (Obowiązkowy parametr musi być określony przed wywołaniem polecenia cmdlet środowiska uruchomieniowego programu Windows PowerShell). Domyślnie parametry są definiowane jako opcjonalne.(A mandatory parameter must be specified before the Windows PowerShell runtime invokes the cmdlet.) By default, parameters are defined as optional.

Aby zdefiniować obowiązkowy parametr, Dodaj Mandatory słowo kluczowe w deklaracji atrybutu parametru i ustaw ją na true , jak pokazano w następującej deklaracji parametru.To define a mandatory parameter, add the Mandatory keyword in the Parameter attribute declaration, and set it to true, as shown in the following parameter declaration.

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

Aby zdefiniować opcjonalny parametr, Pomiń Mandatory słowo kluczowe w deklaracji atrybutu parametru , jak pokazano w następującej deklaracji parametru.To define an optional parameter, omit the Mandatory keyword in the Parameter attribute declaration, as shown in the following parameter declaration.

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

Parametry przełącznikaSwitch Parameters

Środowisko Windows PowerShell udostępnia typ System. Management. Automation. parametr przełącznika , który pozwala na zdefiniowanie parametru, którego wartość jest automatycznie ustawiana na false Jeśli parametr nie zostanie określony, gdy polecenie cmdlet jest wywoływane.Windows PowerShell provides a System.Management.Automation.SwitchParameter type that allows you to define a parameter whose value is automatically set to false if the parameter is not specified when the cmdlet is called. Jeśli to możliwe, użyj parametrów przełącznika zamiast parametrów logicznych.Whenever possible, use switch parameters in place of Boolean parameters.

Rozważmy następujący przykład.Consider the following sample. Domyślnie kilka poleceń cmdlet programu Windows PowerShell nie przekazuje obiektu wyjściowego w dół potoku.By default, several Windows PowerShell cmdlets do not pass an output object down the pipeline. Jednak te polecenia cmdlet mają PassThru parametr Switch, który zastępuje zachowanie domyślne.However, these cmdlets have a PassThru switch parameter that overrides the default behavior. Jeśli PassThru parametr jest określony, gdy są wywoływane te polecenia cmdlet, polecenie cmdlet zwraca obiekt wyjściowy do potoku.If the PassThru parameter is specified when these cmdlets are called, the cmdlet returns an output object to the pipeline.

Jeśli potrzebujesz, aby parametr miał wartość domyślną true , gdy parametr nie jest określony w wywołaniu, rozważ odwrócenie sensu parametru.If you need the parameter to have a default value of true when the parameter is not specified in the call, consider reversing the sense of the parameter. W przypadku przykładu zamiast ustawiania atrybutu parametru na wartość logiczną true , zadeklaruj właściwość jako System. Management. Automation. parametr przełącznika , a następnie ustaw wartość domyślną parametru na false .For sample, instead of setting the parameter attribute to a Boolean value of true, declare the property as the System.Management.Automation.SwitchParameter type, and then set the default value of the parameter to false.

Aby zdefiniować parametr przełącznika, zadeklaruj właściwość jako typ System. Management. Automation. parametr przełącznika , jak pokazano w poniższym przykładzie.To define a switch parameter, declare the property as the System.Management.Automation.SwitchParameter type, as shown in the following sample.

[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 on określony, użyj następującej struktury w ramach jednej z metod przetwarzania danych wejściowych.To make the cmdlet act on the parameter when it is specified, use the following structure within one of the input processing methods.

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

Zobacz teżSee Also

Pisanie polecenia cmdlet programu Windows PowerShellWriting a Windows PowerShell Cmdlet