Tipi di parametri del cmdlet

In questo argomento vengono descritti i diversi tipi di parametri che è possibile dichiarare nei cmdlet. I parametri dei cmdlet possono essere posizionali, denominati, obbligatori, facoltativi o parametri switch.

Parametri posizionali e denominati

Tutti i parametri dei cmdlet sono denominati o posizionali. Per un parametro denominato è necessario digitare il nome del parametro e l'argomento quando si chiama il cmdlet. Un parametro posizionale richiede solo di digitare gli argomenti in ordine relativo. Il sistema esegue quindi il mapping del primo argomento senza nome al primo parametro posizionale. Il sistema esegue il mapping del secondo argomento senza nome al secondo parametro senza nome e così via. Per impostazione predefinita, tutti i parametri dei cmdlet sono denominati parametri.

Per definire un parametro denominato, omettere la parola chiave Position nella dichiarazione di attributo Parameter, come illustrato nella dichiarazione di parametro seguente.

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

Per definire un parametro posizionale, aggiungere la parola chiave Position nella dichiarazione dell'attributo Parameter e quindi specificare una posizione. Nell'esempio seguente il parametro UserName viene dichiarato come parametro posizionale con posizione 0. Ciò significa che il primo argomento della chiamata viene associato automaticamente a questo parametro.

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

Nota

Una buona progettazione dei cmdlet consiglia di dichiarare i parametri più usati come parametri posizionali in modo che l'utente non deve immettere il nome del parametro quando viene eseguito il cmdlet.

I parametri posizionali e denominati accettano singoli argomenti o più argomenti separati da virgole. Sono consentiti più argomenti solo se il parametro accetta una raccolta, ad esempio una matrice di stringhe. È possibile combinare parametri posizionali e denominati nello stesso cmdlet. In questo caso, il sistema recupera prima gli argomenti denominati e quindi tenta di eseguire il mapping degli argomenti senza nome rimanenti ai parametri posizionali.

I comandi seguenti illustrano i diversi modi in cui è possibile specificare singoli e più argomenti per i parametri del cmdlet Get-Command. Si noti che negli ultimi due esempi non è necessario specificare -Name perché il parametro Name è definito come parametro posizionale.

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

Parametri obbligatori e facoltativi

È anche possibile definire i parametri dei cmdlet come parametri obbligatori o facoltativi. È necessario specificare un parametro obbligatorio prima che il runtime di PowerShell richiami il cmdlet. Per impostazione predefinita, i parametri sono definiti come facoltativi.

Per definire un parametro obbligatorio, aggiungere la parola chiave Mandatory nella dichiarazione dell'attributo Parameter e impostarla su true, come illustrato nella dichiarazione di parametro seguente.

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

Per definire un parametro facoltativo, omettere la parola chiave Mandatory nella dichiarazione dell'attributo Parameter, come illustrato nella dichiarazione di parametro seguente.

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

Parametri switch

PowerShell fornisce un tipo di System.Management.Automation.SwitchParameter che consente di definire un parametro il cui valore predefinito false a meno che non venga specificato il parametro quando viene chiamato il cmdlet. Quando possibile, usare parametri switch anziché parametri booleani.

Si consideri l'esempio seguente. Molti cmdlet di PowerShell restituiscono l'output. Tuttavia, questi cmdlet hanno un parametro switch PassThru che esegue l'override del comportamento predefinito. Quando si usa il parametro PassThru, il cmdlet restituisce gli oggetti di output alla pipeline.

Per definire un parametro switch, dichiarare la proprietà come tipo di [SwitchParameter], come illustrato nell'esempio seguente.

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

Per fare in modo che il cmdlet agisca sul parametro quando viene specificato, usare la struttura seguente all'interno di uno dei metodi di elaborazione di input.

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

Per impostazione predefinita, i parametri switch vengono esclusi dai parametri posizionali. È possibile eseguire l'override dell'attributo parametro, ma può confondere gli utenti.

Progettare parametri switch in modo che l'uso del parametro moditi il comportamento predefinito del comando in una modalità meno comune o più complessa. Il comportamento più semplice di un comando deve essere il comportamento predefinito che non richiede l'uso di parametri switch. Basare il comportamento controllato dall'opzione sul valore dell'opzione, non sulla presenza del parametro.

Esistono diversi modi per testare la presenza di parametri switch:

• Invocation.BoundParameters contiene il nome del parametro switch come chiave
• PSCmdlet.ParameterSetName quando l'opzione definisce un set di parametri univoci

Ad esempio, è possibile fornire un valore esplicito per l'opzione usando -MySwitch:$false o splatting. Se si verifica solo la presenza del parametro, il comando si comporta come se il valore dell'opzione sia $true anziché $false.

Vedere anche

scrittura di un cmdlet di Windows PowerShell