Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Breve descrizione
Viene descritto come usare lo splatting per passare parametri ai comandi in PowerShell.
Descrizione lunga
Splatting è un metodo di passaggio di una raccolta di valori di parametro a un comando come unità. PowerShell associa ogni valore della raccolta a un parametro di comando. I valori dei parametri splatted vengono archiviati in variabili splatting denominate, che sono simili a variabili standard, ma iniziano con un simbolo At (@) anziché un segno di dollaro ($). Il simbolo At indica a PowerShell di passare una raccolta di valori anziché un singolo valore.
La tecnica dello "splatting" rende i comandi più brevi e più facili da leggere. È possibile riutilizzare i valori di splatting in diverse chiamate di comando e usare splatting per passare i valori dei parametri dalla variabile automatica $PSBoundParameters ad altri script e funzioni.
A partire da Windows PowerShell 3.0, è anche possibile usare lo splatting per rappresentare tutti i parametri di un comando.
Sintassi
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Per specificare i valori dei parametri per i parametri posizionali, in cui i nomi dei parametri non sono obbligatori, usare la sintassi della matrice. Per specificare coppie nome parametro e valore, usare la sintassi della tabella hash. Il valore splatted può essere visualizzato ovunque nell'elenco dei parametri.
Quando si usa lo splatting, non è necessario utilizzare una tabella hash o un array per passare tutti i parametri. È possibile passare alcuni parametri utilizzando la tecnica dello "splatting" e passare altri in base alla posizione o al nome del parametro. Inoltre, è possibile combinare più oggetti in un unico comando per evitare di passare più di un valore per ogni parametro.
A partire da PowerShell 7.1, è possibile eseguire l'override di un parametro splattato definendo esplicitamente un parametro in un comando.
Splatting con tabelle hash
Utilizzare una tabella hash per associare coppie di nomi di parametri e valori, usando il metodo splat. È possibile usare questo formato per tutti i tipi di parametri, inclusi i parametri posizionali e switch. I parametri posizionali devono essere assegnati in base al nome.
Gli esempi seguenti confrontano due comandi Copy-Item che copiano il file Test.txt nel file Test2.txt nella stessa directory.
Il primo esempio usa il formato tradizionale in cui sono inclusi i nomi dei parametri.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
Il secondo esempio utilizza lo "splatting" delle tabelle hash. Il primo comando crea una tabella hash di coppie parameter-name e parameter-value e la archivia nella variabile $HashArguments. Il secondo comando usa la variabile $HashArguments in un comando con splatting. Il simbolo At (@HashArguments) sostituisce il segno di dollaro ($HashArguments) nel comando .
Per fornire un valore per il parametro switch WhatIf, usare $True o $False.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Annotazioni
Nel primo comando, il simbolo At (@) indica una tabella hash, non un valore espanso. La sintassi per le tabelle hash in PowerShell è: @{<name>=<value>; <name>=<value>; ...}
Splattaggio con array
Usare una matrice per impostare i valori splat per i parametri posizionali, che non richiedono nomi di parametro. I valori devono essere in ordine di numero di posizione nella matrice.
Gli esempi seguenti confrontano due comandi Copy-Item che copiano il file Test.txt nel file Test2.txt nella stessa directory.
Il primo esempio usa il formato tradizionale in cui i nomi dei parametri vengono omessi. I valori dei parametri vengono visualizzati nell'ordine di posizione nel comando .
Copy-Item "test.txt" "test2.txt" -WhatIf
Il secondo esempio usa lo splatting dell'array. Il primo comando crea una matrice dei valori dei parametri e la archivia nella variabile $ArrayArguments. I valori sono in ordine di posizione nella matrice. Il secondo comando utilizza la variabile $ArrayArguments in un comando in splatting. Il simbolo At (@ArrayArguments) sostituisce il segno di dollaro ($ArrayArguments) nel comando .
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Utilizzo del parametro ArgumentList
Diversi cmdlet hanno un parametro ArgumentList usato per passare i valori dei parametri a un blocco di script eseguito dal cmdlet . Il parametro ArgumentList accetta una matrice di valori passati al blocco di script. PowerShell utilizza efficacemente l'array splatting per associare i valori ai parametri del blocco di script. Quando si usa ArgumentList, se è necessario passare una matrice come singolo oggetto associato a un singolo parametro, è necessario eseguire il wrapping della matrice come unico elemento di un'altra matrice.
Nell'esempio seguente è presente un blocco di script che accetta un singolo parametro che è una matrice di stringhe.
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList $array
In questo esempio solo il primo elemento in $array viene passato al blocco di script.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
In questo esempio, $array viene incapsulato in un array in modo che venga passato al blocco di script come singolo oggetto.
Hello World!
Esempi
Esempio 1: Riutilizzare parametri splattati in comandi diversi
In questo esempio viene illustrato come riutilizzare i valori splatted in comandi diversi. I comandi in questo esempio usano il cmdlet Write-Host per scrivere messaggi nella console del programma host. Utilizza una tecnica di "splatting" per specificare i colori di primo piano e di sfondo.
Per modificare i colori di tutti i comandi, è sufficiente modificare il valore della variabile $Colors.
Il primo comando crea una tabella hash di nomi di parametri e valori e archivia la tabella hash nella variabile $Colors.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Il secondo e il terzo comando usano la variabile $Colors per lo splatting in un comando Write-Host. Per usare il $Colors variable, sostituire il segno di dollaro ($Colors) con un simbolo At (@Colors).
#Write a message with the colors in $Colors
Write-Host "This is a test." @Colors
#Write second message with same colors. The position of splatted
#hash table does not matter.
Write-Host @Colors "This is another test."
Esempio 2: Inoltrare i parametri usando $PSBoundParameters
In questo esempio viene illustrato come inoltrare i parametri ad altri comandi utilizzando lo splatting e la $PSBoundParameters variabile automatica.
La variabile automatica $PSBoundParameters è un oggetto dizionario (System.Collections.Generic.Dictionary) che contiene tutti i nomi e i valori dei parametri usati quando viene eseguito uno script o una funzione.
Nell'esempio seguente viene usata la variabile $PSBoundParameters per inoltrare i valori dei parametri passati a uno script o a una funzione dalla funzione Test2 alla funzione Test1. Entrambe le chiamate alla funzione Test1 da Test2 utilizzano lo "splatting".
function Test1
{
param($a, $b, $c)
$a
$b
$c
}
function Test2
{
param($a, $b, $c)
#Call the Test1 function with $a, $b, and $c.
Test1 @PsBoundParameters
#Call the Test1 function with $b and $c, but not with $a
$LimitedParameters = $PSBoundParameters
$LimitedParameters.Remove("a") | Out-Null
Test1 @LimitedParameters
}
Test2 -a 1 -b 2 -c 3
1
2
3
2
3
Esempio 3: Eseguire l'override dei parametri splatted con parametri definiti in modo esplicito
In questo esempio viene illustrato come sovrascrivere un parametro splattato usando parametri definiti esplicitamente. Ciò è utile quando non si vuole creare una nuova tabella hash o modificare un valore nella tabella hash usata per splat.
La variabile $commonParams archivia i parametri per creare macchine virtuali nel percorso di East US. La variabile $allVms è un elenco di macchine virtuali da creare. Ripetiamo l'elenco e usiamo $commonParams per distribuire i parametri al fine di creare ogni macchina virtuale. È tuttavia necessario creare myVM2 in un'area diversa rispetto alle altre macchine virtuali. Anziché modificare la tabella hash $commonParams, è possibile definire in modo esplicito il parametro Location in New-AzVm per sostituire il valore della chiave Location in $commonParams.
$commonParams = @{
ResourceGroupName = "myResourceGroup"
Location = "East US"
VirtualNetworkName = "myVnet"
SubnetName = "mySubnet"
SecurityGroupName = "myNetworkSecurityGroup"
PublicIpAddressName = "myPublicIpAddress"
}
$allVms = @('myVM1','myVM2','myVM3',)
foreach ($vm in $allVms)
{
if ($vm -eq 'myVM2')
{
New-AzVm @commonParams -Name $vm -Location "West US"
}
else
{
New-AzVm @commonParams -Name $vm
}
}
Parametri del comando Splatting
È possibile usare lo splatting per rappresentare i parametri di un comando. Questa tecnica è utile quando si crea una funzione proxy, ovvero una funzione che chiama un altro comando. Questa funzionalità è stata introdotta in Windows PowerShell 3.0.
Per splattare i parametri di un comando, utilizzare @Args per rappresentare i parametri del comando. Questa tecnica è più semplice dell'enumerazione dei parametri di comando e funziona senza revisione anche se i parametri del comando chiamato cambiano.
La funzionalità usa la variabile automatica $Args, che contiene tutti i valori dei parametri non assegnati.
Ad esempio, la funzione seguente chiama il cmdlet Get-Process. In questa funzione, @Args rappresenta tutti i parametri del cmdlet Get-Process.
function Get-MyProcess { Get-Process @Args }
Quando si usa la funzione Get-MyProcess, tutti i parametri e i valori dei parametri non assegnati vengono passati a @Args, come illustrato nei comandi seguenti.
Get-MyProcess -Name PowerShell
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
463 46 225484 237196 719 15.86 3228 powershell
Get-MyProcess -Name PowerShell_Ise -FileVersionInfo
ProductVersion FileVersion FileName
-------------- ----------- --------
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\...
È possibile usare @Args in una funzione con parametri dichiarati in modo esplicito. È possibile usarlo più volte in una funzione, ma tutti i parametri immessi vengono passati a tutte le istanze di @Args, come illustrato nell'esempio seguente.
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
Get-MyCommand -P -C -Name PowerShell
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
408 28 75568 83176 620 1.33 1692 powershell
Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
Visibility : Public
OutputType : {System.String}
Name : powershell.exe
CommandType : Application
ModuleName :
Module :
RemotingCapability : PowerShell
Parameters :
ParameterSets :
HelpUri :
FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell
\v1.0\powershell.exe
InternalName: POWERSHELL
OriginalFilename: PowerShell.EXE.MUI
FileVersion: 10.0.14393.0 (rs1_release.160715-1616
FileDescription: Windows PowerShell
Product: Microsoft Windows Operating System
ProductVersion: 10.0.14393.0
Debug: False
Patched: False
PreRelease: False
PrivateBuild: False
SpecialBuild: False
Language: English (United States)
Note
Se si crea una funzione in una funzione avanzata usando gli attributi CmdletBinding o Parameter, la variabile automatica $args non è più disponibile nella funzione. Le funzioni avanzate richiedono una definizione di parametro esplicita.
PowerShell Desired State Configuration (DSC) non è stato progettato per l'uso dello splatting. Non è possibile usare lo splatting per trasferire valori a una risorsa DSC. Per altre informazioni, vedere l'articolo di Gael Colas Pseudo-Splatting risorse DSC.