about_Splatting
Breve descrizione
Descrive come usare splatting per passare i parametri ai comandi in PowerShell.
Descrizione lunga
Splatting è un metodo per passare una raccolta di valori dei parametri a un comando come unità. PowerShell associa ogni valore nella raccolta a un parametro di comando. I valori dei parametri splatted vengono archiviati in variabili splatting denominate, che sembrano variabili standard, ma iniziano con un simbolo At () anziché un segno dollaro (@$). Il simbolo At indica a PowerShell di passare una raccolta di valori anziché un singolo valore.
Splatting rende i comandi più brevi e più facili da leggere. È possibile riutilizzare i valori di splatting in chiamate di comando diverse e usare splatting per passare i valori dei parametri dalla $PSBoundParameters variabile automatica ad altri script e funzioni.
A partire da Windows PowerShell 3.0, è anche possibile usare 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 necessari, usare la sintassi della matrice. Per specificare coppie di parametri e valori, 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 splatting e passare altri in base alla posizione o al nome del parametro. È anche possibile splat multipli 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 splatted definendo in modo esplicito un parametro in un comando.
Splatting con tabelle hash
Usare una tabella hash per splat parameter name and value pair .Use a hash table to splat parameter name and value pair. È 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 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 parametro-name e parameter-value e lo archivia nella $HashArguments variabile. Il secondo comando usa la $HashArguments variabile in un comando con splatting. Il simbolo At () sostituisce il segno di dollaro (@HashArguments$HashArguments) nel comando .
Per specificare un valore per il parametro dell'opzione 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 splat value per i parametri posizionali, che non richiedono nomi di parametri. I valori devono essere in ordine di numero di posizione nella matrice.
Gli esempi seguenti confrontano 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 vengono omessi i nomi dei parametri. 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 lo 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 () sostituisce il segno di dollaro (@ArrayArguments$ArrayArguments) nel comando .
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Uso 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 viene passato solo il primo elemento in $array 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!
Esempio
Esempio 1: Riutilizzare i parametri 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 splatting per specificare i colori di primo piano e 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"}
I secondi e i terzi comandi usano la variabile per la $Colors splatting in un Write-Host comando. Per usare , $Colors variablesostituire 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: Parametri di inoltro 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 e i valori dei parametri 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 da Test2 usare 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 splatted usando parametri definiti in modo esplicito. Questo è utile quando non si vuole compilare una nuova tabella hash o modificare un valore nella tabella hash che si usa 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 splatare i parametri per creare ogni macchina virtuale. Tuttavia, si vuole myVM2 creare in un'area diversa rispetto alle altre macchine virtuali. Anziché modificare la tabella hash, è possibile definire in modo esplicito il $commonParams 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 dei comandi Splatting
È possibile usare 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à viene introdotta in Windows PowerShell 3.0.
Per splatare i parametri di un comando, usare @Args per rappresentare i parametri dei comandi. Questa tecnica è più semplice rispetto all'enumerazione dei parametri dei comandi e funziona senza revisione anche se i parametri della modifica dei comandi denominati.
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 la definizione esplicita dei parametri.
PowerShell Desired State Configuration (DSC) non è stato progettato per usare splatting. Non è possibile usare splatting per passare i valori in una risorsa DSC. Per altre informazioni, vedere l'articolo Pseudo-Splatting DSC Resources di Gael Colas.