about_Splatting
Descrizione breve
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 hanno un aspetto simile alle 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 splatting rende i comandi più brevi e facili da leggere. È possibile riutilizzare i valori di splatting in diverse chiamate di comando e usare splatting per passare i valori dei $PSBoundParameters parametri dalla variabile automatica 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 esegue lo splatting, non è necessario usare una tabella hash o una matrice per passare tutti i parametri. È possibile passare alcuni parametri usando lo splatting e passare altri in base alla posizione o al nome del parametro. Inoltre, è possibile eseguire lo splat di più oggetti in un singolo comando in modo da non passare più di un valore per ogni parametro.
A partire da PowerShell 7.1, è possibile eseguire l'override di un parametro con splatted definendo in modo esplicito un parametro in un comando.
Splatting con tabelle hash
Usare una tabella hash per impostare coppie nome parametro e valore 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.
Negli esempi seguenti vengono confrontati due Copy-Item comandi 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 usa lo splatting della tabella hash. Il primo comando crea una tabella hash di coppie parameter-name e parameter-value e la archivia nella $HashArguments variabile. Il secondo comando usa la $HashArguments variabile in un comando con splatting. Il simbolo At (@HashArguments) sostituisce il segno di dollaro ($HashArguments) nel comando .
Per specificare un valore per il parametro switch WhatIf , usare $True o $False.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Nota
Nel primo comando, il simbolo At (@) indica una tabella hash, non un valore splatted. La sintassi per le tabelle hash in PowerShell è: @{<name>=<value>; <name>=<value>; ...}
Splatting con matrici
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.
Negli esempi seguenti vengono confrontati due Copy-Item comandi 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 della matrice. Il primo comando crea una matrice dei valori dei parametri e la archivia nella $ArrayArguments variabile . I valori sono in ordine di posizione nella matrice. Il secondo comando usa la $ArrayArguments variabile 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 usa in modo efficace lo splatting della matrice 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 viene $array eseguito il wrapping in una matrice in modo che l'intera matrice venga passata al blocco di script come singolo oggetto.
Hello World!
Esempi
Esempio 1: Riutilizzare i parametri con splatted in comandi diversi
In questo esempio viene illustrato come riutilizzare i valori splatted in comandi diversi. I comandi in questo esempio usano il Write-Host cmdlet per scrivere messaggi nella console del programma host. Usa la splatting per specificare i colori di primo piano e di sfondo.
Per modificare i colori di tutti i comandi, è sufficiente modificare il valore della $Colors variabile.
Il primo comando crea una tabella hash di nomi di parametri e valori e archivia la tabella hash nella $Colors variabile .
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Il secondo e il terzo comando usano la variabile per lo $Colors splatting in un Write-Host comando. Per usare $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 usando splatting e la $PSBoundParameters variabile automatica.
La $PSBoundParameters variabile automatica è un oggetto dizionario (System.Collections.Generic.Dictionary) che contiene tutti i nomi dei parametri e i valori usati quando viene eseguito uno script o una funzione.
Nell'esempio seguente viene usata la $PSBoundParameters variabile per inoltrare i valori dei parametri passati a uno script o a una funzione dalla Test2 funzione alla Test1 funzione. Entrambe le chiamate alla Test1 funzione Test2 usano lo splatting.
function Test1
{
param($a, $b, $c)
"a = $a"
"b = $b"
"c = $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
Test1 -b $PSBoundParameters.b -c $PSBoundParameters.c
}
Test2 -a 1 -b 2 -c 3
a = 1
b = 2
c = 3
a =
b = 2
c = 3
Esempio 3: Eseguire l'override dei parametri splatted con parametri definiti in modo esplicito
In questo esempio viene illustrato come eseguire l'override di un parametro con splatted usando parametri definiti in modo esplicito. Ciò è utile quando non si vuole creare una nuova tabella hash o modificare un valore nella tabella hash usata per splat.
La $commonParams variabile archivia i parametri per creare macchine virtuali nel East US percorso. La $allVms variabile è un elenco di macchine virtuali da creare. Viene eseguito il ciclo dell'elenco e viene usato $commonParams per eseguire lo splating dei parametri per creare ogni macchina virtuale. Tuttavia, si vuole myVM2 creare in un'area diversa rispetto alle altre macchine virtuali. Anziché modificare la $commonParams tabella hash, è possibile definire in modo esplicito il parametro Location in New-AzVm per sostituire il valore della Location chiave 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
}
}
Esempio 4: Uso di più oggetti splatted in un singolo comando
È possibile usare più oggetti splatted in un singolo comando. In questo esempio vengono definiti parametri diversi in tabelle hash separate. Le tabelle hash vengono splatted in un singolo Write-Host comando.
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
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 eseguire lo splat dei parametri di un comando, usare @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 $Args variabile automatica, che contiene tutti i valori dei parametri non assegnati.
Ad esempio, la funzione seguente chiama il Get-Process cmdlet . In questa funzione rappresenta @Args tutti i parametri del Get-Process cmdlet.
function Get-MyProcess { Get-Process @Args }
Quando si usa la Get-MyProcess funzione , 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
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
50 112.76 78.52 16.64 6880 1 powershell
Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Source : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Version : 10.0.22621.3085
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.22621.1 (WinBuild.160101.0800)
FileDescription: Windows PowerShell
Product: Microsoft® Windows® Operating System
ProductVersion: 10.0.22621.1
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 $args variabile automatica 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 passare valori in una risorsa DSC. Per altre informazioni, vedere l'articolo di Gael Colas Sulle risorse DSC pseudo-Splatting.
