ARGOMENTO

about_Functions_Advanced_Parameters

DESCRIZIONE BREVE
Illustra come aggiungere parametri statici e dinamici alle funzioni
che dichiarano l'attributo CmdletBinding.

DESCRIZIONE DETTAGLIATA
È possibile dichiarare i propri parametri quando si scrivono
funzioni ed è possibili scrivere funzioni in modo che possano
accedere ai parametri comuni disponibili ai cmdlet compilati. Per
ulteriori informazioni sui parametri comuni di Windows
PowerShell, vedere about_CommonParameters.

Parametri statici

Nell'esempio seguente viene mostrata una dichiarazione di

parametro che definisce un parametro ComputerName. Questo
parametro presenta le caratteristiche seguenti:

- È obbligatorio.
- Accetta l'input dalla pipeline.
- Accetta una matrice di stringhe come input.

Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)

L'unico attributo obbligatorio che deve essere utilizzato quando

si dichiara un parametro è l'attributo Parameter. Tuttavia, è
possibile dichiarare anche l'attributo Alias e diversi argomenti di
convalida. Non ci sono limiti al numero di attributi che è possibile
aggiungere a una dichiarazione di parametro.

Attributo Parameter

L'attributo Parameter viene utilizzato per dichiarare un

parametro della funzione.
Questo attributo presenta gli argomenti denominati seguenti
utilizzati per definire le caratteristiche del parametro, ad
esempio se il parametro è obbligatorio o facoltativo.

Argomento denominato Mandatory

L'argomento Mandatory indica che il parametro è obbligatorio

quando viene eseguita la funzione. Se non è specificato
questo argomento, il parametro è facoltativo. Nell'esempio
seguente viene mostrata la dichiarazione di un parametro richiesto
quando viene eseguita la funzione.
 Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)

Argomento denominato Position

L'argomento Position specifica la posizione del parametro. Se

questo argomento non è specificato, è necessario specificare
il nome del parametro o l'alias in modo esplicito quando si
imposta il parametro. Inoltre, se nessuno dei parametri di
una funzione dispone di posizioni, in fase di esecuzione di
Windows PowerShell vengono assegnate posizioni a ogni
parametro in base all'ordine in cui i parametri vengono ricevuti.

Nell'esempio seguente viene mostrata la dichiarazione di un

parametro il cui valore deve essere specificato come primo
argomento quando viene eseguito il cmdlet. Si noti che questa
funzione può essere eseguita con o senza la specifica del nome del
parametro.

Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)

Argomento denominato ParameterSetName

L'argomento ParameterSetName specifica il set di parametri al

quale un parametro appartiene. Se non è specificato alcun set di
parametri, il parametro appartiene a tutti i set di parametri
definiti dalla funzione. Questo comportamento implica che ogni set di
parametri deve disporre di un parametro univoco che non sia un membro
di alcun altro set di parametri. Nell'esempio seguente viene mostrata la
dichiarazione di due parametri che appartengono a due set di
parametri diversi.

Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName
)

Param
(
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName
)
 Per ulteriori informazioni sui set di parametri, vedere
l'argomento relativo ai set di parametri dei cmdlet in MSDN
Library all'indirizzo http://go.microsoft.com/fwlink/?LinkId=1
42183 (le informazioni potrebbero essere in lingua inglese).

Argomento denominato ValueFromPipeline

L'argomento ValueFromPipeline specifica che il parametro

accetta input da un oggetto pipeline. Specificare questo
argomento se il cmdlet accede all'oggetto completo, non solo a una
proprietà dell'oggetto. Nell'esempio seguente viene mostrata la
dichiarazione di un parametro ComputerName obbligatorio che accetta
l'oggetto di input passato alla funzione dalla pipeline.

Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)

Argomento denominato ValueFromPipelineByPropertyName

L'argomento valueFromPipelineByPropertyName specifica che il

parametro accetta input da una proprietà di un oggetto pipeline.
Specificare questo attributo se le condizioni seguenti sono vere:

- Il parametro accede a una proprietà dell'oggetto

reindirizzato.

- La proprietà ha lo stesso nome o lo stesso alias del

parametro.

Ad esempio, se la funzione presenta un parametro ComputerName e

l'oggetto reindirizzato presenta una proprietà ComputerName, il
valore della proprietà ComputerName viene assegnato al parametro
ComputerName della funzione.

Nell'esempio seguente viene mostrata la dichiarazione di un

parametro ComputerName che accetta input dalla proprietà
ComputerName dell'oggetto di input passato al cmdlet.

Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)

Argomento denominato ValueFromRemainingArguments

L'argomento ValueFromRemainingArguments specifica che il parametro

accetta tutti gli argomenti restanti non associati ai parametri della
funzione. Nell'esempio seguente viene mostrata la dichiarazione di un
 parametro ComputerName che accetta tutti gli argomenti restanti
dell'oggetto di input passato alla funzione.

Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)

Argomento denominato HelpMessage

L'argomento HelpMessage specifica un messaggio che contiene

una breve descrizione del parametro. Nell'esempio seguente viene
mostrata una dichiarazione di parametro che fornisce una descrizione del
parametro.

Param
(
[parameter(Mandatory=$true,
HelpMessage="Una matrice di nomi di computer.")]
[String[]]
$ComputerName
)

Attributo Alias

L'attributo Alias specifica un altro nome per il parametro. Non vi è

limite al numero di alias che possono essere assegnati a un parametro.
Nell'esempio seguente viene mostrata una dichiarazione di parametro
obbligatoria che aggiunge l'alias "CN" al parametro ComputerName.

Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)

Attributi di convalida dei parametri

Questi attributi definiscono come vengono convalidati gli

argomenti delle funzioni avanzate in fase di esecuzione di Windows
PowerShell.

Attributo di convalida AllowNull

L'attributo AllowNull consente di impostare su Null

l'argomento di un parametro obbligatorio del cmdlet. Nell'esempio
seguente, il parametro ComputerName può contenere un valore Null
anche se questo parametro è obbligatorio.

Param
 (
[parameter(Mandatory=$true)]
[String]
[AllowNull()]
$ComputerName
)

Attributo di convalida AllowEmptyString

L'attributo AllowEmptyString consente una stringa vuota come

argomento di un parametro obbligatorio del cmdlet.
Nell'esempio seguente, il parametro ComputerName può
contenere un una stringa vuota ("") anche se questo parametro è
obbligatorio.

Param
(
[parameter(Mandatory=$true)]
[String]
[AllowEmptyString()]
$ComputerName
)

Attributo di convalida AllowEmptyCollection

L'attributo AllowEmptyCollection consente una raccolta vuota come

argomento di un parametro obbligatorio del cmdlet.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[AllowEmptyCollection()]
$ComputerName
)

Attributo di convalida ValidateCount

L'attributo ValidateCount specifica il numero minimo e massimo di

argomenti che il parametro può accettare. In fase di esecuzione di
Windows PowerShell viene generato un errore se il numero di argomenti
non è compreso in tale intervallo. Nell'esempio seguente, il parametro
ComputerName può presentare da uno a cinque argomenti.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)

Attributo di convalida ValidateLength

L'attributo ValidateLength specifica la lunghezza minima e massima

 dell'argomento del parametro. In fase di esecuzione di Windows
PowerShell viene generato un errore se la lunghezza dell'argomento
del parametro non è compresa in tale intervallo.
Nell'esempio seguente, i nomi dei computer specificati devono
contenere da uno a 10 caratteri.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateLength(1,10)]
$ComputerName
)

Attributo di convalida ValidatePattern

L'attributo ValidatePattern specifica un'espressione regolare che

convalida il modello dell'argomento del parametro. In fase di
esecuzione di Windows PowerShell viene generato un errore se
l'argomento del parametro non corrisponde a questo modello.
Nell'esempio seguente, l'argomento del parametro deve essere
un numero di quattro cifre e ogni cifra deve essere un numero
da 0 a 9.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
$ComputerName
)

Attributo di convalida ValidateRange

L'attributo ValidateRange specifica i valori minimo e massimo

dell'argomento del parametro. In fase di esecuzione di Windows
PowerShell viene generato un errore se l'argomento del parametro non
è compreso in tale intervallo. Nell'esempio seguente, l'argomento del
parametro non può essere minore di 0 o maggiore di 10.

Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)

Attributo di convalida ValidateScript

L'attributo ValidateScript specifica uno script utilizzato per

convalidare l'argomento del parametro. In fase di esecuzione di Windows
PowerShell viene generato un errore se il risultato dello script è
false o se lo script genera un'eccezione. Nell'esempio seguente il
valore del parametro Count deve essere minore di 4.
 Param
(
[parameter()]
[Int]
[ValidateScript({$_ -lt 4})]
$Count
)

Attributo ValidateSet

L'attributo ValidateSet specifica un set di valori validi per

l'argomento del parametro. In fase di esecuzione di Windows
PowerShell viene generato un errore se l'argomento del parametro non
corrisponde a un valore nel set.
Nell'esempio seguente, l'argomento del parametro può
contenere solo i nomi Steve, Mary e Carl.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateRange("Steve", "Mary", "Carl")]
$UserName
)

Attributo di convalida ValidateNotNull

L'attributo ValidateNotNull specifica che non è possibile

impostare l'argomento del parametro su Null. In fase di
esecuzione di Windows PowerShell viene generato un errore se
il valore del parametro è Null.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNull()]
$UserName
)

Attributo di convalida ValidateNotNullOrEmpty

L'attributo ValidateNotNullOrEmpty specifica che l'argomento del

parametro non può essere impostato su Null né essere vuoto. In fase di
esecuzione di Windows PowerShell viene generato un errore se il
parametro è specificato ma il relativo valore è Null, una stringa
vuota o una matrice vuota.

Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNullOrEmpty()]
$UserName
 )

Parametri dinamici

I parametri dinamici sono parametri di un cmdlet, una funzione o uno script

che sono disponibili solo in determinate condizioni.

Ad esempio, diversi cmdlets del provider hanno parametri disponibili solo

quando si utilizza il cmdlet nel percorso del provider. Un parametro dinamico
familiare è il parametro Encoding di un cmdlet Set-Item, che è disponibile
solo quando il cmdlet Set-Item è utilizzato nel percorso del provider
FileSystem.

Per creare un parametro dinamico per una funzione o uno script, utilizzare la
parola chiave Dynamicparam.

La sintassi è la seguente.

DynamicParam {<elenco istruzioni>}

Nell'elenco istruzioni, utilizzare un'istruzione If per specificare le

condizioni in
base alle quali il parametro è disponibile nella funzione.

Utilizzare il cmdlet New-Object per creare un oggetto

System.Management.Automation.RuntimeDefinedParameter per rappresentare il
parametro e specificare il nome.

È inoltre possibile utilizzare il comando New-Object per creare un oggetto

System.Management.Automation.ParameterAttribute per rappresentare attributi del
paramentro, ad esempio Mandatory, Position o ValueFromPipeline, o il relativo
set di parametri.

Di seguito viene riportata una funzione di esempio con parametri standard

chiamati
Name e Path, nonché un parametro dinamico opzionale denominato DP1. Il
parametro DP1 è
nel set di parametri PSet1 e dispone di un tipo Int32. Il parametro DP1 è
disponibile
nella funzione di esempio solo quando il valore del parametro Path contiene
"HKLM:",
il quale indica che è in uso nell'unità del Registro HKEY_LOCAL_MACHINE.

function Sample {
Param ([String]$Name, [String]$Path)

DynamicParam
{
if ($path -match "*HKLM*:")
{
$dynParam1 = new-object
System.Management.Automation.RuntimeDefinedParameter("dp1",
[Int32], $attributeCollection)

$attributes = new-object System.Management.Automation.ParameterAttribute

$attributes.ParameterSetName = 'pset1'
 $attributes.Mandatory = $false

$attributeCollection = new-object
-Type System.Collections.ObjectModel.Collection``1[System.Attribute]
$attributeCollection.Add($attributes)

$paramDictionary = new-object
System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)

return $paramDictionary
} End if
}
}

Per ulteriori informazioni, vedere "RuntimeDefinedParameter Class" in MSDN

Library
all'indirizzo http://go.microsoft.com/fwlink/?LinkID=145130
(le informazioni potrebbero essere in lingua inglese).

VEDERE ANCHE
about_Advanced Functions
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute