about_Functions_Advanced_Parameters

Descrizione breve

Viene illustrato come aggiungere parametri alle funzioni avanzate.

Descrizione lunga

È possibile aggiungere parametri alle funzioni avanzate scritte e usare gli attributi e gli 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. Lo splatting è valido per funzioni semplici e avanzate. Per altre informazioni, vedere about_Functions e about_Splatting.

Conversione dei tipi di valori dei parametri

Quando si forniscono stringhe come argomenti ai 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 invariante delle impostazioni cultura dei valori dei parametri.

Al contrario, viene eseguita una conversione sensibile alle impostazioni cultura durante l'associazione di 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 in formato 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-or-false tramite 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 l'output dei 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 attentamente 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 che sia necessario un valore.

Considerazioni sulla progettazione dei parametri switch

• Ai parametri switch non devono essere assegnati valori predefiniti. L'impostazione predefinita deve essere sempre false.

• I parametri switch vengono esclusi dai parametri posizionali per impostazione predefinita. Anche quando altri parametri sono posizionati in modo implicito, i parametri switch non sono. È possibile eseguirne l'override nell'attributo Parameter, ma confonderà gli utenti.

• I parametri switch devono essere progettati in modo che l'impostazione di un comando passi dal 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 di parametri switch.

• I parametri switch non devono essere obbligatori. L'unico caso in cui è necessario rendere obbligatorio un parametro switch è quando è necessario distinguere un set di parametri.

• È possibile impostare in modo esplicito un'opzione da un valore booleano con -MySwitch:$boolValue e 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 del provider hanno parametri disponibili solo quando il cmdlet viene usato nell'unità del provider o in un percorso specifico dell'unità del provider. Ad esempio, il parametro Encoding è 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 viene usato un altro parametro 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 per gli utenti. Per trovare un parametro dinamico, l'utente deve trovarsi nel percorso del provider, usare il parametro ArgumentList del Get-Command cmdlet oppure usare il parametro Path di Get-Help.

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 di 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 Name e Path 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:, a indicare che viene usato nell'unità HKEY_LOCAL_MACHINE del 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

In questa sezione vengono descritti gli attributi che è possibile aggiungere ai parametri della 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 di 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é come funzione semplice, 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.

Usare la sintassi seguente per dichiarare l'attributo Parameter , un argomento e un valore di argomento. Le parentesi che racchiudono l'argomento e il relativo valore devono seguire Parameter senza spazi intermedi.

param(
    [Parameter(Argument=value)]
    $ParameterName
)

Usare le virgole per separare gli argomenti tra parentesi. Utilizzare la sintassi seguente per dichiarare due argomenti dell'attributo Parameter .

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

I tipi di argomento booleani dell'attributo Parameter predefinito su False quando vengono omessi dall'attributo Parameter . Impostare il valore dell'argomento su $true o semplicemente elencare l'argomento in base al nome. Ad esempio, gli attributi Parameter 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, in alternativa all'uso dell'attributo CmdletBinding , le parentesi che seguono il nome dell'attributo sono comunque obbligatorie.

param(
    [Parameter()]
    $ParameterName
)

Argomento obbligatorio

L'argomento Mandatory indica che il parametro è obbligatorio. Se questo argomento non viene 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 Position

L'argomento Position determina se il nome del parametro è obbligatorio 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 senza nome nel comando.

Se l'argomento Position non viene specificato, il nome del parametro o un alias o un'abbreviazione del nome di parametro deve precedere il valore del parametro ogni volta che il parametro viene usato in un comando.

Per impostazione predefinita, tutti i parametri di funzione sono posizionali. PowerShell assegna 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 basarsi 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 un 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 set di Computer 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'"
}

Una dimostrazione del piping di un oggetto con la proprietà ComputerName sarà quindi:

[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 delay bind 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 che contiene 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 previsto del parametro.

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 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-Help cmdlet .
• 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 nomi di tipo 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 usare 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 non 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 impostare tale comportamento come predefinito e rimuovere il parametro dalla funzione . Tuttavia, non si vuole 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 della scheda. 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. Tuttavia, a differenza di ValidateSet, 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 come 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. Per questo scenario è possibile usare l'attributo AllowEmptyString .

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 è compreso nell'intervallo specificato.

La dichiarazione di parametro seguente crea un parametro ComputerName che accetta da uno a 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 di almeno 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 criterio 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 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.
• Non Negativo : 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 , il valore convalidato viene mappato 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 di 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 precedente, 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 di 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 precedente, 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 della scheda. 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 Basso, Medio o Alto.

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 tale 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 che usano 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 l'unità User nelle configurazioni di sessione Just Enough Amministrazione istration (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.

Vedi anche

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute