about_Functions_Advanced_Parameters
Breve descrizione
Viene illustrato come aggiungere parametri alle funzioni avanzate.
Descrizione lunga
È possibile aggiungere parametri alle funzioni avanzate scritte e usare attributi e argomenti dei parametri per limitare i valori dei parametri inviati dagli utenti con il parametro.
I parametri aggiunti alla funzione sono disponibili per gli utenti oltre ai parametri comuni aggiunti automaticamente a tutti i cmdlet e alle funzioni avanzate. Per altre informazioni sui parametri comuni di PowerShell, vedere about_CommonParameters.
A partire da PowerShell 3.0, è possibile usare splatting con @Args per rappresentare i parametri in un comando. Splatting è valido su funzioni semplici e avanzate. Per altre informazioni, vedere about_Functions e about_Splatting.
Conversione dei tipi di valori dei parametri
Quando si specificano stringhe come argomenti a parametri che prevedono un tipo diverso, PowerShell converte in modo implicito le stringhe nel tipo di destinazione del parametro. Le funzioni avanzate eseguono l'analisi cultura-invariante dei valori dei parametri.
Al contrario, viene eseguita una conversione sensibile alle impostazioni cultura durante l'associazione dei parametri per i cmdlet compilati.
In questo esempio viene creato un cmdlet e una funzione script che accettano un [datetime] parametro. Le impostazioni cultura correnti vengono modificate per usare le impostazioni tedesche.
Una data formattata in tedesco viene passata al parametro.
# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
using System;
using System.Management.Automation;
[Cmdlet("Get", "Date_Cmdlet")]
public class GetFooCmdlet : Cmdlet {
[Parameter(Position=0)]
public DateTime Date { get; set; }
protected override void ProcessRecord() {
WriteObject(Date);
}
}
'@ -PassThru | % Assembly | Import-Module
[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'
Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00
Come illustrato in precedenza, i cmdlet usano l'analisi sensibile alle impostazioni cultura per convertire la stringa.
# Define an equivalent function.
function Get-Date_Func {
param(
[DateTime] $Date
)
process {
$Date
}
}
[cultureinfo]::CurrentCulture = 'de-DE'
# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'
Get-Date_Func $dateStr
Le funzioni avanzate usano l'analisi invariante delle impostazioni cultura, che genera l'errore seguente.
Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."
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.
Nell'esempio seguente viene illustrata la dichiarazione di un parametro ComputerName con le caratteristiche seguenti:
- È obbligatorio (obbligatorio).
- Accetta l'input dalla pipeline.
- Accetta una matrice di stringhe come input.
param(
[Parameter(Mandatory=$true, ValueFromPipeline=$true)]
[string[]]$ComputerName
)
Parametri opzionali
I parametri switch sono parametri che non accettano alcun valore di parametro. Invece, comunicano un valore booleano true-o-false attraverso la loro presenza o assenza, in modo che quando un parametro switch è presente ha un valore true e quando assente ha un valore false .
Ad esempio, il parametro Recurse di Get-ChildItem è un parametro switch.
Per creare un parametro switch in una funzione, specificare il switch tipo nella definizione del parametro.
Ad esempio, la funzione può avere un'opzione per restituire i dati come matrice di byte:
param([switch]$AsByteArray)
I parametri switch sono facili da usare e sono preferiti rispetto ai parametri booleani, che hanno una sintassi meno naturale per PowerShell.
Ad esempio, per usare un parametro switch, l'utente digita il parametro nel comando.
-IncludeAll
Per usare un parametro booleano, l'utente digita il parametro e un valore booleano.
-IncludeAll $true
Quando si creano parametri switch, scegliere con attenzione il nome del parametro. Assicurarsi che il nome del parametro comunichi l'effetto del parametro all'utente. Evitare termini ambigui, ad esempio Filter o Maximum che potrebbero implicare un valore obbligatorio.
Considerazioni sulla progettazione dei parametri switch
I parametri di opzione non devono essere specificati valori predefiniti. Devono sempre impostare il valore predefinito su false.
I parametri switch sono esclusi dai parametri posizionali per impostazione predefinita. Anche se altri parametri sono posizionali in modo implicito, i parametri di opzione non sono. È possibile eseguire l'override di tale elemento nell'attributo Parameter, ma confonde gli utenti.
I parametri switch devono essere progettati in modo che l'impostazione sposta un comando dal relativo comportamento predefinito a una modalità meno comune o più complessa. Il comportamento più semplice di un comando deve essere il comportamento predefinito che non richiede l'uso dei parametri switch.
I parametri di opzione non devono essere obbligatori. L'unico caso in cui è necessario rendere obbligatorio un parametro switch è quando è necessario differenziare un set di parametri.
L'impostazione esplicita di un commutatore da un booleano può essere eseguita con
-MySwitch:$boolValuee in splatting con$params = @{ MySwitch = $boolValue }.I parametri switch sono di tipo
SwitchParameter, che converte in modo implicito in booleano. La variabile di parametro può essere usata direttamente in un'espressione condizionale. Ad esempio:if ($MySwitch) { ... }Non è necessario scrivere
if ($MySwitch.IsPresent) { ... }
Parametri dinamici
I parametri dinamici sono parametri di un cmdlet, di una funzione o di uno script disponibili solo in determinate condizioni.
Ad esempio, diversi cmdlet provider dispongono di parametri disponibili solo quando il cmdlet viene usato nell'unità provider o in un percorso specifico dell'unità provider. Ad esempio, il parametro Codifica è disponibile nei Add-Contentcmdlet , Get-Contente Set-Content solo quando viene usato in un'unità file system.
È anche possibile creare un parametro visualizzato solo quando un altro parametro viene usato nel comando della funzione 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 individuare dagli utenti. Per trovare un parametro dinamico, l'utente deve trovarsi nel percorso del provider, usare il parametro ArgumentList del cmdlet oppure usare il parametro Path di Get-HelpGet-Command .
Per creare un parametro dinamico per una funzione o uno script, usare la DynamicParam parola chiave.
La sintassi è la seguente:
dynamicparam {<statement-list>}
Nell'elenco delle istruzioni usare un'istruzione if per specificare le condizioni in cui il parametro è disponibile nella funzione.
Nell'esempio seguente viene illustrata una funzione con parametri standard denominati Nome e Percorso e un parametro dinamico facoltativo denominato KeyCount. Il parametro KeyCount si trova nel ByRegistryPath set di parametri e ha un tipo di Int32. Il parametro KeyCount è disponibile nella Get-Sample funzione solo quando il valore del parametro Path inizia con HKLM:, che indica che viene usato nell'unità del HKEY_LOCAL_MACHINE Registro di sistema.
function Get-Sample {
[CmdletBinding()]
param([string]$Name, [string]$Path)
DynamicParam
{
if ($Path.StartsWith("HKLM:"))
{
$parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
ParameterSetName = "ByRegistryPath"
Mandatory = $false
}
$attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
$attributeCollection.Add($parameterAttribute)
$dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
'KeyCount', [Int32], $attributeCollection
)
$paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
$paramDictionary.Add('KeyCount', $dynParam1)
return $paramDictionary
}
}
}
Per altre informazioni, vedere la documentazione per il tipo RuntimeDefinedParameter .
Attributi dei parametri
Questa sezione descrive gli attributi che è possibile aggiungere ai parametri di funzione.
Tutti gli attributi sono facoltativi. Tuttavia, se si omette l'attributo CmdletBinding , per essere riconosciuto come funzione avanzata, la funzione deve includere l'attributo Parameter .
È possibile aggiungere uno o più attributi in ogni dichiarazione di parametro. Non esiste alcun limite al numero di attributi che è possibile aggiungere a una dichiarazione di parametro.
Attributo del parametro
L'attributo Parameter viene usato per dichiarare gli attributi dei parametri della funzione.
L'attributo Parameter è facoltativo ed è possibile ometterlo se nessuno dei parametri delle funzioni necessita di attributi. Tuttavia, per essere riconosciuto come funzione avanzata, anziché una semplice funzione, una funzione deve avere l'attributo CmdletBinding o l'attributo Parameter o entrambi.
L'attributo Parameter include argomenti che definiscono le caratteristiche del parametro, ad esempio se il parametro è obbligatorio o facoltativo.
Utilizzare la sintassi seguente per dichiarare l'attributo Parameter , un argomento e un valore di argomento. Le parentesi che racchiudeno l'argomento e il relativo valore devono seguire Parametro senza spazio di intervento.
param(
[Parameter(Argument=value)]
$ParameterName
)
Usare virgole per separare gli argomenti all'interno delle parentesi. Utilizzare la sintassi seguente per dichiarare due argomenti dell'attributo Parameter .
param(
[Parameter(Argument1=value1, Argument2=value2)]
$ParameterName
)
I tipi di argomenti booleani dell'attributo Parameter predefinito su False quando omesso dall'attributo Parameter . Impostare il valore dell'argomento su $true o semplicemente elencare l'argomento in base al nome. Ad esempio, gli attributi di parametro seguenti sono equivalenti.
param(
[Parameter(Mandatory=$true)]
)
# Boolean arguments can be defined using this shorthand syntax
param(
[Parameter(Mandatory)]
)
Se si usa l'attributo Parameter senza argomenti, come alternativa all'uso dell'attributo CmdletBinding , le parentesi che seguono il nome dell'attributo sono ancora necessarie.
param(
[Parameter()]
$ParameterName
)
Argomento obbligatorio
L'argomento Mandatory indica che il parametro è obbligatorio. Se questo argomento non è specificato, il parametro è facoltativo.
Nell'esempio seguente viene dichiarato il parametro ComputerName . Usa l'argomento Mandatory per rendere obbligatorio il parametro.
param(
[Parameter(Mandatory)]
[string[]]$ComputerName
)
Argomento Posizione
L'argomento Position determina se il nome del parametro è necessario quando il parametro viene usato in un comando. Quando una dichiarazione di parametro include l'argomento Position , il nome del parametro può essere omesso e PowerShell identifica il valore del parametro senza nome in base alla posizione o all'ordine nell'elenco dei valori dei parametri non denominati nel comando.
Se l'argomento Position non è specificato, il nome del parametro o un alias di nome parametro o un'abbreviazione, deve precedere il valore del parametro ogni volta che il parametro viene usato in un comando.
Per impostazione predefinita, tutti i parametri della funzione sono posizionali. PowerShell assegna i numeri di posizione ai parametri nell'ordine in cui i parametri vengono dichiarati nella funzione.
Per disabilitare questa funzionalità, impostare il valore dell'argomento dell'attributo PositionalBindingCmdletBinding su $False. L'argomento Position ha la precedenza sul valore dell'argomento dell'attributo PositionalBindingCmdletBinding . Per altre informazioni, vedere PositionalBinding in about_Functions_CmdletBindingAttribute.
Il valore dell'argomento Position viene specificato come integer. 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 le posizioni a ogni parametro in base all'ordine in cui vengono dichiarati i parametri. Tuttavia, come procedura consigliata, non fare affidamento su questa assegnazione. Quando si desidera che i parametri siano posizionali, usare l'argomento Position .
Nell'esempio seguente viene dichiarato il parametro ComputerName . Usa l'argomento Position con un valore pari a 0. Di conseguenza, quando -ComputerName viene omesso dal comando, il relativo valore deve essere il primo o solo il valore del parametro senza nome nel comando.
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
Argomento ParameterSetName
L'argomento ParameterSetName specifica il set di parametri a cui appartiene un parametro. Se non viene specificato alcun set di parametri, il parametro appartiene a tutti i set di parametri definiti dalla funzione. Per essere univoco, ogni set di parametri deve avere almeno un parametro che non è membro di alcun altro set di parametri.
Nota
Per un cmdlet o una funzione, è previsto un limite di 32 set di parametri.
Nell'esempio seguente viene dichiarato un parametro ComputerName nel Computer set di parametri, un parametro UserName nel User set di parametri e un parametro Summary in entrambi i set di parametri.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
È possibile specificare un ParameterSetName solo valore in ogni argomento e un ParameterSetName solo argomento in ogni attributo Parameter . Per includere un parametro in più set di parametri, aggiungere altri attributi parameter .
Nell'esempio seguente viene aggiunto in modo esplicito il parametro Summary ai set di Computer parametri e User . Il parametro Summary è facoltativo nel Computer set di parametri e obbligatorio nel set di User parametri.
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter(ParameterSetName="Computer")]
[Parameter(Mandatory, ParameterSetName="User")]
[switch]$Summary
)
Per altre informazioni sui set di parametri, vedere Informazioni sui set di parametri.
Argomento ValueFromPipeline
L'argomento ValueFromPipeline indica che il parametro accetta l'input da un oggetto pipeline. Specificare questo argomento se la funzione accetta l'intero oggetto, non solo una proprietà dell'oggetto .
L'esempio seguente dichiara un parametro ComputerName obbligatorio e accetta un oggetto passato alla funzione dalla pipeline.
param(
[Parameter(Mandatory, ValueFromPipeline)]
[string[]]$ComputerName
)
Argomento ValueFromPipelineByPropertyName
L'argomento ValueFromPipelineByPropertyName indica che il parametro accetta l'input da una proprietà di un oggetto pipeline. La proprietà dell'oggetto deve avere lo stesso nome o alias del parametro .
Ad esempio, se la funzione ha un parametro ComputerName e l'oggetto piped ha una proprietà ComputerName , il valore della proprietà ComputerName viene assegnato al parametro ComputerName della funzione.
Nell'esempio seguente viene dichiarato un parametro ComputerName obbligatorio e viene accettato l'input dalla proprietà ComputerName dell'oggetto passata alla funzione tramite la pipeline.
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Si consideri un'implementazione di una funzione usando questo argomento:
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
Quindi, una dimostrazione dell'invio di piping di un oggetto con la proprietà ComputerName sarà:
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
Nota
Un parametro tipizzato che accetta l'input della pipeline (by Value) o (by PropertyName) consente l'uso di blocchi di script di associazione ritardata nel parametro .
Il blocco di script di associazione ritardata viene eseguito automaticamente durante ParameterBinding. Il risultato è associato al parametro . L'associazione ritardata non funziona per i parametri definiti come tipo ScriptBlock o System.Object. Il blocco di script viene passato senza essere richiamato. Per altre informazioni sui blocchi di script di associazione ritardata , vedere about_Script_Blocks.
Argomento ValueFromRemainingArguments
L'argomento ValueFromRemainingArguments indica che il parametro accetta tutti i valori del parametro nel comando che non sono assegnati ad altri parametri della funzione.
Nell'esempio seguente viene dichiarato un parametro Value obbligatorio e un parametro Remaining che accetta tutti i valori dei parametri rimanenti inviati alla funzione.
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$Remaining
)
"Found $($Remaining.Count) elements"
for ($i = 0; $i -lt $Remaining.Count; $i++) {
"${i}: $($Remaining[$i])"
}
}
Test-Remainder first one,two
Found 2 elements
0: one
1: two
Argomento HelpMessage
L'argomento HelpMessage specifica una stringa contenente una breve descrizione del parametro o del relativo valore. Se si esegue il comando senza il parametro obbligatorio, PowerShell richiede l'input. Per visualizzare il messaggio della Guida, digitare !? al prompt e premere INVIO.
Nell'esempio seguente viene dichiarato un parametro ComputerName obbligatorio e un messaggio della Guida che spiega il valore del parametro previsto.
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
Output di esempio:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
Se non è disponibile alcuna Guida basata su commenti per la funzione, questo messaggio viene visualizzato nell'output Get-Help -Full .
Questo argomento non ha alcun effetto sui parametri facoltativi.
attributo Alias
L'attributo Alias stabilisce un nome alternativo per il parametro . Non esiste alcun limite al numero di alias che è possibile assegnare a un parametro.
Nell'esempio seguente viene illustrata una dichiarazione di parametro che aggiunge gli alias CN e MachineName al parametro ComputerName obbligatorio.
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
Attributo Credential
L'attributo Credential viene usato per indicare che il parametro accetta le credenziali. Nell'esempio seguente viene illustrata una dichiarazione di parametro che usa l'attributo Credential .
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
Attributo sperimentale
Usare l'attributo Experimental per dichiarare codice come sperimentale. Per una descrizione completa dell'attributo, vedere about_Experimental_Features.
Attributo PSDefaultValue
PSDefaultValue specifica il valore predefinito di un parametro di comando in uno script. Queste informazioni vengono visualizzate dal Get-Help cmdlet . Per visualizzare le informazioni sul valore predefinito, la funzione deve includere la Guida basata su commenti. Ad esempio:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
Usare Get-Help per visualizzare le informazioni sul valore predefinito.
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
Argomenti dell'attributo PSDefaultValue
L'attributo PSDefaultValue ha due argomenti:
- Guida : stringa che descrive il valore predefinito. Queste informazioni vengono visualizzate dal
Get-Helpcmdlet . - Value : valore predefinito del parametro.
Entrambi gli argomenti sono facoltativi. Se non si specificano argomenti, Get-Help viene visualizzato il valore assegnato al parametro .
Attributo PSTypeName
Non è possibile usare i nomi dei tipi estesi in una dichiarazione di tipo. L'attributo PSTypeName* consente di limitare il tipo del parametro al tipo esteso.
In questo esempio il Test-Connection cmdlet restituisce un tipo esteso. È possibile utilizzare l'attributo PSTypeName per limitare il tipo del parametro al tipo esteso.
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
Attributo System.Obsolete
Usare l'attributo System.Obsolete per contrassegnare i parametri che non sono più supportati. Ciò può essere utile quando si vuole rimuovere un parametro da una funzione, ma non si vogliono interrompere gli script esistenti che usano la funzione.
Si consideri ad esempio una funzione con un parametro switch NoTypeInformation che controlla se le informazioni sul tipo sono incluse nell'output. Si vuole rendere il comportamento predefinito e rimuovere il parametro dalla funzione. Tuttavia, non si vogliono interrompere gli script esistenti che usano la funzione . È possibile contrassegnare il parametro come obsoleto e aggiungere un messaggio che spiega la modifica.
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
Attributo SupportsWildcards
L'attributo SupportsWildcards viene usato per indicare che il parametro accetta valori jolly. Nell'esempio seguente viene illustrata una dichiarazione di parametro per un parametro Path obbligatorio che supporta i valori jolly.
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
L'uso di questo attributo non abilita automaticamente il supporto dei caratteri jolly. Lo sviluppatore di cmdlet deve implementare il codice per gestire l'input con caratteri jolly. I caratteri jolly supportati possono variare in base all'API sottostante o al provider PowerShell. Per altre informazioni, vedere about_Wildcards.
Attributi di completamento degli argomenti
Attributo ArgumentCompletions
L'attributo ArgumentCompletions consente di aggiungere valori di completamento tramite tabulazione a un parametro specifico. È necessario definire un attributo ArgumentCompletions per ogni parametro che richiede il completamento tramite tabulazione. L'attributo ArgumentCompletions è simile a ValidateSet. Entrambi gli attributi accettano un elenco di valori da presentare quando l'utente preme Tab dopo il nome del parametro. A differenza di ValidateSet, tuttavia, i valori non vengono convalidati.
Questo attributo è stato introdotto in PowerShell 6.0.
Per altre informazioni, vedere about_Functions_Argument_Completion.
Attributo ArgumentCompleter
L'attributo ArgumentCompleter consente di aggiungere valori di completamento tramite tabulazione a un parametro specifico. È necessario definire un attributo ArgumentCompleter per ogni parametro che richiede il completamento tramite tabulazione. Analogamente a DynamicParameters, i valori disponibili vengono calcolati in fase di esecuzione quando l'utente preme Tab dopo il nome del parametro.
Per altre informazioni, vedere about_Functions_Argument_Completion.
Attributi di convalida dei parametri e delle variabili
Gli attributi di convalida indirizzano PowerShell a testare i valori dei parametri inviati dagli utenti quando chiamano la funzione avanzata. Se i valori dei parametri non superano il test, viene generato un errore e la funzione non viene chiamata. La convalida dei parametri viene applicata solo all'input fornito e tutti gli altri valori, ad esempio i valori predefiniti, non vengono convalidati.
È anche possibile usare gli attributi di convalida per limitare i valori che gli utenti possono specificare per le variabili.
[AllowNull()] [int]$number = 7
Gli attributi di convalida possono essere applicati a qualsiasi variabile, non solo ai parametri. È possibile definire la convalida per qualsiasi variabile all'interno di uno script.
Nota
Quando si usano attributi con una variabile tipizzata, è consigliabile dichiarare l'attributo prima del tipo.
Se si dichiara un tipo con un'interruzione di riga prima dell'attributo e del nome della variabile, il tipo viene considerato come una propria istruzione.
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
Se si dichiara un attributo di convalida dopo un tipo, il valore assegnato viene convalidato prima della conversione del tipo, causando errori di convalida imprevisti.
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
Attributo di convalida AllowNull
L'attributo AllowNull consente al valore di un parametro obbligatorio di essere $null. Nell'esempio seguente viene dichiarato un parametro ComputerInfo hashtable che può avere un valore Null .
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
Nota
L'attributo AllowNull non funziona se il convertitore di tipi è impostato su string perché il tipo stringa non accetterà un valore Null. È possibile usare l'attributo AllowEmptyString per questo scenario.
Attributo di convalida AllowEmptyString
L'attributo AllowEmptyString consente al valore di un parametro obbligatorio di essere una stringa vuota (""). Nell'esempio seguente viene dichiarato un parametro ComputerName che può avere un valore stringa vuoto.
param(
[Parameter(Mandatory)]
[AllowEmptyString()]
[string]$ComputerName
)
Attributo di convalida AllowEmptyCollection
L'attributo AllowEmptyCollection consente al valore di un parametro obbligatorio di essere una raccolta @()vuota. Nell'esempio seguente viene dichiarato un parametro ComputerName che può avere un valore di raccolta vuoto.
param(
[Parameter(Mandatory)]
[AllowEmptyCollection()]
[string[]]$ComputerName
)
Attributo di convalida ValidateCount
L'attributo ValidateCount specifica il numero minimo e massimo di valori di parametro accettati da un parametro. PowerShell genera un errore se il numero di valori dei parametri nel comando che chiama la funzione non rientra in tale intervallo.
La dichiarazione di parametro seguente crea un parametro ComputerName che accetta uno o cinque valori di parametro.
param(
[Parameter(Mandatory)]
[ValidateCount(1,5)]
[string[]]$ComputerName
)
Attributo di convalida ValidateLength
L'attributo ValidateLength specifica il numero minimo e massimo di caratteri in un parametro o valore di variabile. PowerShell genera un errore se la lunghezza di un valore specificato per un parametro o una variabile non rientra nell'intervallo.
Nell'esempio seguente ogni nome computer deve contenere da uno a dieci caratteri.
param(
[Parameter(Mandatory)]
[ValidateLength(1,10)]
[string[]]$ComputerName
)
Nell'esempio seguente il valore della variabile $text deve essere un minimo di un carattere di lunghezza e un massimo di dieci caratteri.
[ValidateLength(1,10)] [string] $text = 'valid'
Attributo di convalida ValidatePattern
L'attributo ValidatePattern specifica un'espressione regolare confrontata con il parametro o il valore della variabile. PowerShell genera un errore se il valore non corrisponde al modello di espressione regolare.
Nell'esempio seguente il valore del parametro deve contenere un numero a quattro cifre e ogni cifra deve essere un numero da zero a nove.
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
Nell'esempio seguente il valore della variabile $ticketID deve essere esattamente un numero a quattro cifre e ogni cifra deve essere un numero da zero a nove.
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111
Attributo di convalida ValidateRange
L'attributo ValidateRange specifica un intervallo numerico o un valore di enumerazione ValidateRangeKind per ogni parametro o valore di variabile. PowerShell genera un errore se un valore non rientra in tale intervallo.
L'enumerazione ValidateRangeKind consente i valori seguenti:
- Positivo : numero maggiore di zero.
- Negativo : numero minore di zero.
- NonPositive : numero minore o uguale a zero.
- NonNegative : numero maggiore o uguale a zero.
Nell'esempio seguente il valore del parametro Attempts deve essere compreso tra zero e dieci.
param(
[Parameter(Mandatory)]
[ValidateRange(0,10)]
[Int]$Attempts
)
Nell'esempio seguente il valore della variabile $number deve essere compreso tra zero e dieci.
[ValidateRange(0,10)] [int]$number = 5
Nell'esempio seguente il valore della variabile $number deve essere maggiore di zero.
[ValidateRange("Positive")] [int]$number = 1
Attributo di convalida ValidateScript
L'attributo ValidateScript specifica uno script usato per convalidare un parametro o un valore di variabile. PowerShell invia tramite pipe il valore allo script e genera un errore se lo script restituisce $false o se lo script genera un'eccezione.
Quando si usa l'attributo ValidateScript , viene eseguito il mapping del valore convalidato alla $_ variabile . È possibile usare 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(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]$EventDate
)
Nell'esempio seguente il valore della variabile $date deve essere minore o uguale alla data e all'ora correnti.
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
Nota
Se si usa ValidateScript, non è possibile passare un $null valore al parametro . Quando si passa un valore Null ValidateScript non è in grado di convalidare l'argomento.
Override del messaggio di errore predefinito
A partire da PowerShell 6, è possibile eseguire l'override del messaggio di errore predefinito generato quando un valore specificato non è valido con l'argomento ErrorMessage . Specificare una stringa di formato composito. Il 0 componente dell'indice usa il valore di input.
Il 1 componente di indice usa ScriptBlock usato per convalidare il valore di input.
Nell'esempio seguente il valore del parametro EventDate deve essere maggiore o uguale alla data e all'ora correnti. Se il valore non è valido, il messaggio di errore segnala che la data e l'ora specificate sono troppo vecchie.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Quando il valore specificato è una data passata, viene restituito il messaggio di errore personalizzato.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
È possibile applicare ulteriore formattazione nella stringa con componenti stringa di formato facoltativi.
Nell'esempio seguente il valore del parametro EventDate deve essere maggiore o uguale alla data e all'ora correnti. Se il valore non è valido, il messaggio di errore segnala che la data specificata è troppo vecchia.
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
Quando il valore specificato è una data passata, viene restituito il messaggio di errore personalizzato.
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
Attributo ValidateSet
L'attributo ValidateSet specifica un set di valori validi per un parametro o una variabile e abilita il completamento tramite tabulazione. PowerShell genera un errore se un parametro o un valore di variabile non corrisponde a un valore nel set. Nell'esempio seguente il valore del parametro Detail può essere solo Low, Average o High.
param(
[Parameter(Mandatory)]
[ValidateSet("Low", "Average", "High")]
[string[]]$Detail
)
Nell'esempio seguente il valore della variabile $flavor deve essere Chocolate, Strawberry o Vanilla.
[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"
La convalida viene eseguita ogni volta che la variabile viene assegnata anche all'interno dello script. Ad esempio, il codice seguente genera un errore in fase di esecuzione:
param(
[ValidateSet("hello", "world")]
[string]$Message
)
$Message = "bye"
In questo esempio viene restituito l'errore seguente in fase di esecuzione:
MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.
L'uso di ValidateSet abilita anche l'espansione tramite tabulazioni dei valori per tale parametro. Per altre informazioni, vedere about_Tab_Expansion.
Valori ValidateSet dinamici tramite classi
È possibile usare una classe per generare dinamicamente i valori per ValidateSet in fase di esecuzione. Nell'esempio seguente i valori validi per la variabile $Sound vengono generati tramite una classe denominata SoundNames che controlla tre percorsi del file system per i file audio disponibili:
Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
[string[]] GetValidValues() {
$SoundPaths = '/System/Library/Sounds/',
'/Library/Sounds','~/Library/Sounds'
$SoundNames = ForEach ($SoundPath in $SoundPaths) {
If (Test-Path $SoundPath) {
(Get-ChildItem $SoundPath).BaseName
}
}
return [string[]] $SoundNames
}
}
La [SoundNames] classe viene quindi implementata come valore ValidateSet dinamico come segue:
param(
[ValidateSet([SoundNames])]
[string]$Sound
)
Nota
La IValidateSetValuesGenerator classe è stata introdotta in PowerShell 6.0
Attributo di convalida ValidateNotNull
L'attributo ValidateNotNull specifica che il valore del parametro non può essere $null. Quando il valore è $null, PowerShell genera un'eccezione.
L'attributo ValidateNotNull è progettato per essere usato quando il parametro è facoltativo e il tipo non è definito o ha un convertitore di tipi che non può convertire in modo implicito un valore Null come oggetto. Se si specifica un tipo che converte in modo implicito un valore Null, ad esempio una stringa, il valore Null viene convertito in una stringa vuota anche quando si usa l'attributo ValidateNotNull . Per questo scenario usare l'attributo ValidateNotNullOrEmpty .
Nell'esempio seguente il valore del parametro ID non può essere $null.
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
Attributo di convalida ValidateNotNullOrEmpty
L'attributo ValidateNotNullOrEmpty specifica che il valore assegnato non può essere uno dei valori seguenti:
$null- una stringa vuota (
"") - matrice vuota (
@())
Quando il valore non è valido, PowerShell genera un'eccezione.
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
Attributo di convalida ValidateDrive
L'attributo ValidateDrive specifica che il valore del parametro deve rappresentare il percorso, che fa riferimento solo alle unità consentite. PowerShell genera un errore se il valore del parametro fa riferimento a unità diverse da quelle consentite. L'esistenza del percorso, ad eccezione dell'unità stessa, non viene verificata.
Se si usa il percorso relativo, l'unità corrente deve trovarsi nell'elenco delle unità consentite.
param(
[ValidateDrive("C", "D", "Variable", "Function")]
[string]$Path
)
Attributo di convalida ValidateUserDrive
L'attributo ValidateUserDrive specifica che il valore del parametro deve rappresentare nell'unità User . PowerShell genera un errore se il percorso fa riferimento a un'unità diversa. L'attributo di convalida verifica solo l'esistenza del prefisso dell'unità del percorso.
Se si usa il percorso relativo, l'unità corrente deve essere User.
function Test-UserDrivePath{
[OutputType([bool])]
param(
[Parameter(Mandatory, Position=0)]
[ValidateUserDrive()]
[string]$Path
)
$True
}
Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument 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'. Cannot
find drive. A drive with the name 'User' does not exist.
È possibile definire User l'unità nelle configurazioni di sessione JUST Enough Administration (JEA). Per questo esempio viene creata l'unità User: .For this example, we create the User: drive.
New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name Used (GB) Free (GB) Provider Root
---- --------- --------- -------- ----
User 75.76 24.24 FileSystem C:\Users\ExampleUser
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True
Attributo di convalida ValidateTrustedData
Questo attributo è stato aggiunto in PowerShell 6.1.1.
A questo punto, l'attributo viene usato internamente da PowerShell stesso e non è destinato all'utilizzo esterno.