about_Splatting

  • Articolo

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&reg; Windows&reg; 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.

Vedi anche