About Functions Advanced Parameters (Italiano)

• 10/27/2020
• 20 minutes to read
• • S
  • s
  • s
  • c
  • g

Short description

Explains how to add parameters to advanced functions.,

Descrizione lunga

È possibile aggiungere parametri alle funzioni avanzate che si scrivono e utilizzare attributi e argomenti parameter per limitare i valori dei parametri inviati da functionusers con il parametro.

I parametri aggiunti alla funzione sono disponibili per gli utenti in aggiunta ai parametri comuni che PowerShell aggiunge automaticamente a tutti i cmdlet e alle funzioni avanzate. Per ulteriori informazioni sui commonparameters di PowerShell, vedere about_CommonParameters.

A partire da PowerShell 3.,0, è possibile utilizzare splatting con @Args per rappresentare i parametri in un comando. Splatting è valido su semplice e avanzatofunzioni. Per ulteriori informazioni, vedere about_Functions e About_splatting.

Tipo di conversione dei valori dei parametri

Quando si forniscono stringhe come argomenti a parametri che prevedono un tipo diverso, PowerShell converte implicitamente le stringhe nel tipo di destinazione dei parametri.Le funzioni avanzate eseguono l’analisi cultura-invariante dei valori dei parametri.

Al contrario, una conversione sensibile alla cultura viene eseguita durante parameterbinding per cmdlet compilati.,

In questo esempio, creiamo un cmdlet e una funzione di script che prendono un parametro. La cultura attuale viene modificata per utilizzare le impostazioni tedesche.Una data formattata in tedesco viene passata al parametro.

Dienstag, 19. Juni 2018 00:00:00

Come mostrato sopra, i cmdlet utilizzano l’analisi sensibile alla cultura per convertire la stringa.

Le funzioni avanzate utilizzano l’analisi cultura-invariante, che si traduce nell’errore seguente.

Parametri statici

I parametri statici sono parametri sempre disponibili nella funzione.,La maggior parte dei parametri nei cmdlet e negli script di PowerShell sono parametri statici.

L’esempio seguente mostra la dichiarazione di un parametro ComputerName che ha le seguenti caratteristiche:

• È obbligatorio (obbligatorio).
• Prende input dalla pipeline.
• Prende un array di stringhe come input.

Param( ] $ComputerName)

Attributi dei parametri

Questa sezione descrive gli attributi che è possibile aggiungere ai parametri di funzione.

Tutti gli attributi sono opzionali., Tuttavia, se si omette CmdletBindingattribute, quindi per essere riconosciuto come una funzione avanzata, la funzione deve includere l’attributo del parametro.

È possibile aggiungere uno o più attributi in ogni dichiarazione di parametro. Non c’è limite al numero di attributi che è possibile aggiungere a un parameterdeclaration.

Attributo parametro

L’attributo parametro viene utilizzato per dichiarare gli attributi di functionparameters.

L’attributo del parametro è facoltativo e puoi ometterlo se nessuno dei parametri delle tue funzioni ha bisogno di attributi., Ma, per essere riconosciuta come una funzione avanzata, piuttosto che una semplice funzione, una funzione deve avere sia l’attributo CmdletBinding o l’attributo Parameter, o entrambi.

L’attributo Parameter ha argomenti che definiscono le caratteristiche del parametro, ad esempio se il parametro è obbligatorio o facoltativo.

Utilizzare la seguente sintassi per dichiarare l’attributo del parametro,un argomento e un valore di argomento. Le parentesi che racchiudono l’argomento e il suo valore devono seguire il parametro senza spazio intermedio.,

Param( $ParameterName)

Usa le virgole per separare gli argomenti tra parentesi. Utilizzare il seguente syntax per dichiarare due argomenti dell’attributo Parameter.

Param( )

I tipi di argomenti booleani dell’attributo parametro sono predefiniti a Falsequando omessi dall’attributo parametro. Impostare il valore dell’argomento su $true o semplicemente elencare l’argomento per nome. Ad esempio, gli attributi followingParameter sono equivalenti.,

Se si utilizza l’attributo Parameter senza argomenti, in alternativa all’uso dell’attributo CmdletBinding, sono comunque necessarie le parentesi che seguono il nome dell’attributo.

Param( $ParameterName)

Argomento obbligatorio

L’argomento Mandatory indica che il parametro è richiesto. Se thisargument non è specificato, il parametro è facoltativo.

Il seguente esempio dichiara il parametro ComputerName. Utilizza l’argomentoMandatory per rendere obbligatorio il parametro.,

Param( ] $ComputerName)

Argomento posizione

L’argomento Position determina se il nome del parametro è richiesto quandoil parametro viene utilizzato in un comando. Quando una dichiarazione di parametro include l’argomentoPosition, il nome del parametro può essere omesso e PowerShellidentifica il valore del parametro senza nome in base alla sua posizione o ordine nell’elenco dei valori dei parametri senza nome nel comando.,

Se l’argomento Position non è specificato, il nome del parametro, o un alias o abbreviazione parametername, deve precedere il valore del parametro ogni volta che il parametro viene utilizzato in un comando.

Per impostazione predefinita, tutti i parametri di funzione sono posizionali. PowerShell assegna positionnumbers ai parametri nell’ordine in cui i parametri sono dichiarati in thefunction. Per disabilitare questa funzione, impostare il valore dell’argomentoPositionalBindingdell’attributo CmdletBinding su$False., L’argomentoPositionha la precedenza sul valore dell’argomentoPositionalBinding dell’attributo CmdletBinding. Per ulteriori informazioni, vedere PositionalBinding in about_Functions_CmdletBindingAttribute.

Il valore dell’argomentoPosition viene specificato come numero intero. Un valore di posizione pari a 0 rappresenta la prima posizione nel comando, un valore di posizione pari a 1 rappresenta la seconda posizione nel comando e così via.,

Se una funzione non ha parametri posizionali, PowerShell assegna posizioni a ciascun parametro in base all’ordine in cui i parametri sono dichiarati.Tuttavia, come best practice, non fare affidamento su questo incarico. Quando si desidera che i parametri siano posizionali, utilizzare l’argomentoPosition.

Il seguente esempio dichiara il parametro ComputerName. Utilizza l’argomentoPosition con un valore di 0. Di conseguenza, quando -ComputerName isomitted dal comando, il suo valore deve essere il primo o l’unico parametervalue senza nome nel comando.,

Param( ] $ComputerName)

ParameterSetName argument

L’argomento specifica il set di parametri a cui appartiene aparameter. Se non viene specificato alcun set di parametri, il parametro appartiene atutti i set di parametri definiti dalla funzione. Pertanto, per essere univoci, ogni set di parametri deve avere almeno un parametro che non è un membro di nessun altro set di parametri.

L’esempio seguente dichiara un parametro ComputerName nel set di parametriComputer, un parametro UserName nel set di parametriUser e un parametro aSummary in entrambi i set di parametri.

È possibile specificare un solo valore in ogni argomento e un solo argomento in ogni attributo del parametro. Per indicare che aparameter appare in più di un set di parametri, aggiungere Parameterattributes aggiuntivi.,

Il seguente esempio aggiunge esplicitamente il parametro Summary ai set di parametriComputere User. Il parametro di riepilogo è facoltativo nel set di parametriComputer e obbligatorio nel set di parametriUser.

Per ulteriori informazioni sui set di parametri, vedere Informazioni sui set di parametri.

Argomento ValueFromPipeline

L’argomentoValueFromPipeline indica che il parametro accetta inputfrom un oggetto pipeline., Specificare questo argomento se la funzione accetta l’oggetto entire, non solo una proprietà dell’oggetto.

L’esempio seguente dichiara un parametro ComputerName che è obbligatorio e accetta un oggetto passato alla funzione dalla pipeline.

Param( ] $ComputerName)

argomento ValueFromPipelineByPropertyName

L’argomento ValueFromPipelineByPropertyName indica che il parameteraccepts input da una proprietà di un oggetto pipeline. La proprietà object deve avere lo stesso nome o alias del parametro.,

Ad esempio, se la funzione ha un parametro ComputerName e pipedobject ha una proprietà ComputerName, il valore di ComputerNameproperty viene assegnato al parametro ComputerName della funzione.

L’esempio seguente dichiara un parametro ComputerName che è obbligatorio e accetta input dalla proprietà ComputerName dell’oggetto che è passata alla funzione attraverso la pipeline.,

Param( ] $ComputerName)

ValueFromRemainingArguments argomento

L’argomento ValueFromRemainingArguments indica che il parametro accetta tutti i valori del parametro nel comando che non sono assegnati ad altri parametri della funzione.

Il seguente esempio dichiara un parametro Valore che è obbligatorio e aRemaining parametro che accetta tutti i valori dei parametri rimanenti thatare inviato alla funzione.

Found 2 elements0: one1: two

Argomento HelpMessage

L’argomento HelpMessage specifica una stringa che contiene una breve descrizione del parametro o del suo valore. PowerShell visualizza questo messaggio nel prompt che appare quando un valore di parametro obbligatorio manca da un comando. Thisargument non ha alcun effetto sui parametri opzionali.

L’esempio seguente dichiara un parametro ComputerName obbligatorio e un messaggio ahelp che spiega il valore del parametro previsto.,

Se non esiste un’altra sintassi di aiuto basata su commenti per la funzione (ad esempio,.SYNOPSIS), questo messaggio viene visualizzato anche nell’outputGet-Help.

Param( ] $ComputerName)

Attributo Alias

L’attributo Alias stabilisce un nome alternativo per il parametro.Non c’è limite al numero di alias che è possibile assegnare a un parametro.

L’esempio seguente mostra una dichiarazione di parametro che aggiunge gli alias CN andMachineName al parametro ComputerName obbligatorio.,

Param( ] $ComputerName)

Attributo SupportsWildcards

L’attributo SupportsWildcards viene utilizzato per indicare che il parametroaccetta i valori dei caratteri jolly. L’esempio seguente mostra una dichiarazione di parametroper un parametro Percorso obbligatorio che supporta i valori jolly.

Param( ] $Path)

L’utilizzo di questo attributo non abilita automaticamente il supporto dei caratteri jolly. cmdletdeveloper deve implementare il codice per gestire l’input con caratteri jolly. Il wildcardssupported può variare in base all’API sottostante o al provider PowerShell. Per maggiori informazioni, vedere about_Wildcards.,

Attributi di convalida dei parametri e delle variabili

Attributi di convalida PowerShell diretto per testare i valori dei parametri che userssubmit quando chiamano la funzione avanzata. Se i valori dei parametri non riescono thetest, viene generato un errore e la funzione non viene chiamata. Validationis parametro applicato solo all’input fornito e tutti gli altri valori come valori predefiniti non sono convalidati.

È inoltre possibile utilizzare gli attributi di convalida per limitare i valori che gli utenti possono specificare per le variabili., Quando si utilizza un convertitore di tipo insieme all’attributo avalidation, il convertitore di tipo deve essere definito prima dell’attributo.

 $number = 7

AllowNull validation attribute

L’attributo AllowNull consente al valore di un parametro obbligatorio di essere$null. L’esempio seguente dichiara un parametro hashtable ComputerInfo che può avere un valore null.

Param( $ComputerInfo)

Attributo di convalida AllowEmptyString

L’attributo AllowEmptyString consente al valore di un parametro obbligatorio di essere una stringa vuota (""). L’esempio seguente dichiara un ComputerNameparameter che può avere un valore stringa vuoto.

Param( $ComputerName)

Attributo di convalida AllowEmptyCollection

L’attributo AllowEmptyCollection consente al valore di un mandatoryparameter di essere una raccolta vuota @()., L’esempio seguente dichiara il parametro aComputerName che può avere un valore di raccolta vuoto.

Param( ] $ComputerName)

ValidateCount validation attribute

L’attributo ValidateCount specifica il numero minimo e massimo di valori di parametro che un parametro accetta. PowerShell genera un errore se il numero di valori dei parametri nel comando che chiama la funzione è al di fuori dell’intervallo.

La seguente dichiarazione di parametro crea un parametro ComputerName che richiede da uno a cinque valori di parametro.,

Param( ] $ComputerName)

ValidateLength validation attribute

L’attributo ValidateLength specifica il numero minimo e massimo di caratteri in un parametro o valore variabile. PowerShell genera un errore se la lunghezza di un valore specificato per un parametro o una variabile è al di fuori del intervallo.

Nell’esempio seguente, ogni nome del computer deve contenere da uno a dieci caratteri.

Param( ] $ComputerName)

Nell’esempio seguente, il valore della variabile$number deve essere minimo di un carattere e massimo di dieci caratteri.,

$number = '01'

ValidatePattern validation attribute

L’attributo ValidatePattern specifica un’espressione regolare che ‘ rispetto al valore del parametro o della variabile. PowerShell genera un errore seil valore non corrisponde al modello di espressione regolare.,

Nell’esempio seguente, il valore del parametro deve contenere un numero di quattro cifre e ogni cifra deve essere un numero da zero a nove.

Param( ")] ] $ComputerName)

Nell’esempio seguente, il valore della variabile$number deve essere esattamente un numero di quattro cifre, e ogni cifra deve essere un numero da zero a nove.

$")]$number = 1111

ValidateRange validation attribute

L’attributo ValidateRange specifica un intervallo numerico o un valore enum aValidateRangeKind per ciascun parametro o valore variabile.PowerShell genera un errore se un valore è al di fuori di tale intervallo.,

L’enum ValidateRangeKind consente i seguenti valori:

• Positivo – Un numero maggiore di zero.
• Negativo-Un numero inferiore a zero.
• NonPositive – Un numero minore o uguale a zero.
• Non negativo – Un numero maggiore o uguale a zero.

Nell’esempio seguente, il valore del parametro Tentativi deve esseretra zero e dieci.

Param( $Attempts)

Nell’esempio seguente, il valore della variabile$number deve essere compreso tra zero e dieci.,

$number = 5

Nell’esempio seguente, il valore della variabile$number deve essere maggiore di zero.

$number = 1

ValidateScript validation attribute

L’attributo ValidateScript specifica uno script utilizzato per convalidare un parametro o un valore variabile. PowerShell invia il valore allo script e genera un errore se lo script restituisce $false o se lo script genera anexception.,

Quando si utilizza l’attributo ValidateScript, il valore che viene validatedis mappato alla variabile$_. È possibile utilizzare la variabile$_ per fare riferimento al valore nello script.

Nell’esempio seguente, il valore del parametro EventDate deve essere maggiore o uguale alla data corrente.

Param( $EventDate)

Nell’esempio seguente, il valore della variabile$date deve essere maggiore o uguale alla data e all’ora correnti.,

$date = (Get-Date)

Attributo ValidateSet

L’attributo ValidateSet specifica un insieme di valori validi per una variabile parameteror e abilita il completamento della scheda. PowerShell genera un errore se aparameter o valore variabile non corrisponde a un valore nel set. Nell’esempio seguente, il valore del parametro Detail può essere solo Basso, Medio o alto.,

Param( ] $Detail)

Nell’esempio seguente, il valore della variabile$flavor deve essere o Cioccolato, Fragola o Vaniglia.

$flavor = "Strawberry"

La convalida si verifica ogni volta che la variabile viene assegnata anche all’interno di thescript. Ad esempio, i seguenti risultati in un errore in fase di runtime:

Param( $Message)$Message = "bye"

Valori validateSet dinamici

È possibile utilizzare una classe per generare dinamicamente i valori per ValidateSetat runtime., Nell’esempio seguente, i valori validi per la variabile$Sound sono generati tramite una Classe denominata SoundNames che controlla threefilesystem percorsi disponibili i file audio:

classe è quindi implementato come una dinamica ValidateSet valueas segue:

Param( )] $Sound)

ValidateNotNull convalida attributo

Il ValidateNotNull attributo specifica che il valore del parametro non può essere$null. PowerShell genera un errore se il valore del parametro è $null.,

L’attributo ValidateNotNull è progettato per essere utilizzato quando il parametro isoptional e il tipo non è definito o ha un convertitore di tipo che può’convertire implicitamente un valore null come oggetto. Se si specifica un tipo che convertirà implicitamente un valore null come una stringa, il valore null viene convertito in una stringa vuota anche quando si utilizza ValidateNotNullattribute. Per questo scenario utilizzare ValidateNotNullOrEmpty

Nell’esempio seguente, il valore del parametro ID non può essere $null.,

Param( $ID)

ValidateNotNullOrEmpty validation attribute

L’attributo ValidateNotNullOrEmpty specifica che il parametro valuecan’t essere $null e non può essere una stringa vuota (""). PowerShell genera anerror se il parametro viene utilizzato in una chiamata di funzione, ma il suo valore è$null, anempty string (""), o un array vuoto@().,

Param( ] $UserName)

ValidateDrive validatedrive attributo

L’attributo ValidateDrive specifica che il valore del parametro deve rappresentare il percorso, che si riferisce solo alle unità consentite. PowerShell Genera un errore se il valore del parametro si riferisce a unità diverse da theallowed. L’esistenza del percorso, ad eccezione dell’unità stessa, non è verificata.

Se si utilizza il percorso relativo, l’unità corrente deve essere nell’elenco unità consentite.,

Param( $Path)

ValidateUserDrive validation attribute

L’attributo ValidateUserDrive specifica che il valore del parametro deve rappresentare il percorso, che si riferisce all’unità User. PowerShell genera anerror se il percorso si riferisce a un’unità diversa. L’attributo di convalida onlytests per l’esistenza della porzione di unità del percorso.

Se si utilizza il percorso relativo, l’unità corrente deve essere User.,

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument drive C does not belong to the set of approved drives: User.Supply a path argument with an approved drive.

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannotfind drive. A drive with the name 'User' does not exist.

È possibile definireUser drive in Just Enough Administration (JEA) sessionconfigurations. Per questo esempio, creiamo l’Utente: drive.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH

True

ValidateTrustedData validation attribute

Questo attributo è stato aggiunto in PowerShell 6.1.1.

In questo momento, l’attributo viene utilizzato internamente da PowerShell stesso e non è destinato all’uso esterno.,

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 cmdlet provider hanno parametri disponibili solo quando il cmdlet viene utilizzato nell’unità provider o in un particolare percorso dell’unità provider. Ad esempio, il parametro di codifica è disponibile sui cmdletAdd-Content, Get-Content e Set-Content solo quando viene utilizzato in un’unità del file system.,

È anche possibile creare un parametro che appare solo quando un altro parametro viene utilizzato nel comando function o quando un altro parametro ha un determinato valore.

I parametri dinamici possono essere utili, ma usarli solo quando necessario, perchépossono essere difficili da scoprire per gli utenti. Per trovare un parametro dinamico, l’utente deve trovarsi nel percorso del provider, utilizzare il parametro ArgumentList del cmdletGet-Command o utilizzare il parametro Path di Get-Help.

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

La sintassi è la seguente:

DynamicParam {<statement-list>}

Nell’elenco delle istruzioni, utilizzare un’istruzioneIf per specificare le condizioni sottoche il parametro è disponibile nella funzione.

Utilizzare il New-Object cmdlet per creare aSystem.Gestione.Automazione.RuntimeDefinedParameter oggetto per representthe parametro e specificare il suo nome.

È possibile utilizzare un New-Object comando per creare aSystem.Gestione.Automazione.,Oggetto ParameterAttribute per representattributes del parametro, ad esempio Obbligatorio, Position, orValueFromPipeline o il relativo set di parametri.

L’esempio seguente mostra una funzione di esempio con parametri standard Nomenome e Percorso e un parametro dinamico opzionale denominato DP1. Il parametro DP1 è nel set di parametriPSet1 e ha un tipo diInt32.,Il parametro DP1 è disponibile nella funzioneGet-Sample solo quando il valore del parametro Path inizia conHKLM:, indicando che viene utilizzato nell’unità di registroHKEY_LOCAL_MACHINE.

Per ulteriori informazioni, vedere il parametro Untimedefined.

Parametri di commutazione

I parametri di commutazione sono parametri senza valore di parametro. Sono effectiveonly quando vengono utilizzati e hanno un solo effetto.

Ad esempio, il parametro NoProfile di powershell.exe è un parametro di commutazione.,

Per creare un parametro di commutazione in una funzione, specificare il tipo Switch nella definizione del parametro.

Ad esempio:

Param(<ParameterName>)

Oppure, è possibile utilizzare un altro metodo:

Param( $<ParameterName>)

I parametri di commutazione sono facili da usare e sono preferiti rispetto ai parametri booleani,che hanno una sintassi più difficile.

Ad esempio, per utilizzare un parametro switch, l’utente digita il parametro nel comando.

-IncludeAll

Per utilizzare un parametro booleano, l’utente digita il parametro e un valore booleano.,

-IncludeAll:$true

Quando si creano i parametri dell’interruttore, scegliere con attenzione il nome del parametro. Assicurati che il nome del parametro comunichi l’effetto del parametro all’utente.Evitare termini ambigui, come Filtro o Massimo che potrebbero implicare avalue è richiesto.

Attributo ArgumentCompleter

L’attributo ArgumentCompleter consente di aggiungere valori di completamento della scheda a un parametro specifico. È necessario definire un attributo ArgumentCompleter per ogni parametro che necessita del completamento della scheda., Simile a DynamicParameters, i valori disponibili vengono calcolati in fase di esecuzione quando l’utente preme Tabafter il nome del parametro.

Per aggiungere un attributo ArgumentCompleter, è necessario definire un blocco di script che determina i valori. Il blocco script deve prendere quanto segueparametri nell’ordine specificato di seguito. I nomi dei parametri non contano comei valori sono forniti posizionalmente.,

La sintassi è la seguente:

ArgumentCompleter script block

I parametri del blocco script sono impostati sui seguenti valori:

• $commandName (Posizione 0) – Questo parametro è impostato sul nome del comando per il quale il blocco script fornisce il completamento della scheda.
• $parameterName (Posizione 1) – Questo parametro è impostato sul parametro whosevalue richiede il completamento della scheda.
• $wordToComplete (Posizione 2) – Questo parametro è impostato su valore che l’utente ha fornito prima di premere Tab., Il tuo blocco di script dovrebbe usarequesto valore per determinare i valori di completamento della scheda.
• $commandAst (Posizione 3) – Questo parametro è impostato su Abstract SyntaxTree (AST) per la linea di ingresso corrente. Per ulteriori informazioni, vedere Ultima classe.
• $fakeBoundParameters(Posizione 4) – Questo parametro è impostato su un hashtablecontenente il$PSBoundParameters per il cmdlet, prima che l’utente premesse la scheda. Per ulteriori informazioni, vedere about_automatic_variables.,

Il blocco di script ArgumentCompleter deve srotolare i valori utilizzando thepipeline, ad esempio ForEach-Object, Where-Object, o un altro metodo adatto.La restituzione di un array di valori fa sì che PowerShell tratti l’intero array come un valore di completamento della scheda.

L’esempio seguente aggiunge il completamento della scheda al parametro Value. Se viene specificato il parametro Valore onlythe, vengono visualizzati tutti i possibili valori o argomenti forValue. Quando viene specificato il parametro Type, il parametro Value visualizza solo i valori possibili per quel tipo.,

Inoltre, l’operatore -like garantisce che se l’utente digita il seguente comando e utilizza il completamento della scheda, viene restituito solo Apple.

Test-ArgumentCompleter -Type Fruits -Value A

Vedi anche

about_Automatic_Variables

about_functions_advanced

about_Functions_Advanced

about_Functions_Advanced_Methods

about_functions_advanced_parameters

about_Functions_OutputTypeAttribute