about_Splatting
Description courte
Décrit comment utiliser la splatting pour passer des paramètres à des commandes dans PowerShell.
Description longue
La plateforme est une méthode de transmission d’une collection de valeurs de paramètres à une commande en tant qu’unité. PowerShell associe chaque valeur de la collection à un paramètre de commande. Les valeurs des paramètres plates sont stockées dans des variables de mise en forme nommées, qui ressemblent à des variables standard, mais commencent par un symbole At (@
) au lieu d’un signe dollar ($
). Le symbole At indique à PowerShell que vous transmettez une collection de valeurs, au lieu d’une seule valeur.
La mise en forme rend vos commandes plus courtes et plus faciles à lire. Vous pouvez réutiliser les valeurs de platissement dans différents appels de commande et utiliser la mise en forme pour passer des valeurs de paramètre de la $PSBoundParameters
variable automatique à d’autres scripts et fonctions.
À compter de Windows PowerShell 3.0, vous pouvez également utiliser la mise en forme pour représenter tous les paramètres d’une commande.
Syntax
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Pour fournir des valeurs de paramètre pour les paramètres positionnels, dans lequel les noms de paramètres ne sont pas obligatoires, utilisez la syntaxe de tableau. Pour fournir des paires nom et valeur de paramètre, utilisez la syntaxe de la table de hachage. La valeur plate peut apparaître n’importe où dans la liste des paramètres.
Lors de l’platissement, vous n’avez pas besoin d’utiliser une table de hachage ou un tableau pour passer tous les paramètres. Vous pouvez passer certains paramètres à l’aide de la plaque et passer d’autres par position ou par nom de paramètre. En outre, vous pouvezplater plusieurs objets dans une seule commande afin de ne pas passer plusieurs valeurs pour chaque paramètre.
À compter de PowerShell 7.1, vous pouvez remplacer un paramètre splatted en définissant explicitement un paramètre dans une commande.
Mise en forme avec des tables de hachage
Utilisez une table de hachage pour splat parameter name and value pairs. Vous pouvez utiliser ce format pour tous les types de paramètres, y compris les paramètres positionnels et de commutateur. Les paramètres positionnels doivent être attribués par nom.
Les exemples suivants comparent deux Copy-Item
commandes qui copient le fichier Test.txt dans le fichier Test2.txt dans le même répertoire.
Le premier exemple utilise le format traditionnel dans lequel les noms de paramètres sont inclus.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
Le deuxième exemple utilise la plaque de table de hachage. La première commande crée une table de hachage de paires parameter-name et parameter-value et les stocke dans la $HashArguments
variable. La deuxième commande utilise la $HashArguments
variable dans une commande avec la plaque. Le symbole At (@HashArguments
) remplace le signe dollar ($HashArguments
) dans la commande.
Pour fournir une valeur pour le paramètre de commutateur WhatIf , utilisez $True
ou $False
.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Notes
Dans la première commande, le symbole At (@
) indique une table de hachage, et non une valeur platie. La syntaxe des tables de hachage dans PowerShell est la suivante : @{<name>=<value>; <name>=<value>; ...}
Mise en forme avec des tableaux
Utilisez un tableau pour mettre en forme des valeurs pour les paramètres positionnels, qui ne nécessitent pas de noms de paramètres. Les valeurs doivent être dans l’ordre de position dans le tableau.
Les exemples suivants comparent deux Copy-Item
commandes qui copient le fichier Test.txt dans le fichier Test2.txt dans le même répertoire.
Le premier exemple utilise le format traditionnel dans lequel les noms de paramètres sont omis. Les valeurs des paramètres apparaissent dans l’ordre de position dans la commande.
Copy-Item "test.txt" "test2.txt" -WhatIf
Le deuxième exemple utilise la plaque de tableau. La première commande crée un tableau des valeurs de paramètre et les stocke dans la $ArrayArguments
variable. Les valeurs sont en position dans le tableau. La deuxième commande utilise la $ArrayArguments
variable dans une commande en splatting. Le symbole At (@ArrayArguments
) remplace le signe dollar ($ArrayArguments
) dans la commande.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Utilisation du paramètre ArgumentList
Plusieurs applets de commande ont un paramètre ArgumentList utilisé pour passer des valeurs de paramètre à un bloc de script exécuté par l’applet de commande. Le paramètre ArgumentList prend un tableau de valeurs passées au bloc de script. PowerShell utilise efficacement la mise en forme de tableau pour lier les valeurs aux paramètres du bloc de script. Lorsque vous utilisez ArgumentList, si vous devez passer un tableau en tant qu’objet unique lié à un seul paramètre, vous devez encapsuler le tableau comme seul élément d’un autre tableau.
L’exemple suivant contient un bloc de script qui accepte un seul paramètre qui est un tableau de chaînes.
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList $array
Dans cet exemple, seul le premier élément est $array
passé au bloc de script.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
Dans cet exemple, $array
est encapsulé dans un tableau afin que l’ensemble du tableau soit passé au bloc de script en tant qu’objet unique.
Hello World!
Exemples
Exemple 1 : Réutiliser les paramètres platis dans différentes commandes
Cet exemple montre comment réutiliser des valeurs plates dans différentes commandes. Les commandes de cet exemple utilisent l’applet Write-Host
de commande pour écrire des messages dans la console du programme hôte. Il utilise la plaque pour spécifier les couleurs de premier plan et d’arrière-plan.
Pour modifier les couleurs de toutes les commandes, modifiez simplement la valeur de la $Colors
variable.
La première commande crée une table de hachage de noms et de valeurs de paramètres et stocke la table de hachage dans la $Colors
variable.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Les deuxième et troisième commandes utilisent la $Colors
variable pour la platissement dans une Write-Host
commande. Pour utiliser le $Colors variable
signe dollar () remplacez le signe dollar ($Colors
) par un symbole 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."
Exemple 2 : Transférer des paramètres à l’aide de $PSBoundParameters
Cet exemple montre comment transférer leurs paramètres à d’autres commandes à l’aide de la plateforme et de la $PSBoundParameters
variable automatique.
La $PSBoundParameters
variable automatique est un objet dictionnaire (System.Collections.Generic.Dictionary) qui contient tous les noms et valeurs de paramètres utilisés lors de l’exécution d’un script ou d’une fonction.
Dans l’exemple suivant, nous utilisons la $PSBoundParameters
variable pour transférer les valeurs de paramètres passées à un script ou une fonction d’une Test2
fonction à la Test1
fonction. Les deux appels à la Test1
fonction Test2
utilisent la plaque.
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
Exemple 3 : Remplacer les paramètres platis avec des paramètres définis explicitement
Cet exemple montre comment remplacer un paramètre splatted à l’aide de paramètres définis explicitement. Cela est utile lorsque vous ne souhaitez pas générer de nouvelle table de hachage ou modifier une valeur dans la table de hachage que vous utilisez pour la plateforme.
La $commonParams
variable stocke les paramètres pour créer des machines virtuelles à l’emplacement East US
. La $allVms
variable est une liste de machines virtuelles à créer. Nous parcourons la liste et nous utilisons $commonParams
pour mettre en place les paramètres pour créer chaque machine virtuelle. Toutefois, nous voulons myVM2
être créés dans une région différente de celle des autres machines virtuelles. Au lieu d’ajuster la $commonParams
table de hachage, vous pouvez définir explicitement le paramètre Location pour New-AzVm
remplacer la valeur de la Location
clé dans $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
}
}
Paramètres de commande de platissement
Vous pouvez utiliser la splatting pour représenter les paramètres d’une commande. Cette technique est utile lorsque vous créez une fonction proxy, c’est-à-dire une fonction qui appelle une autre commande. Cette fonctionnalité est introduite dans Windows PowerShell 3.0.
Pourplater les paramètres d’une commande, utilisez-le @Args
pour représenter les paramètres de commande. Cette technique est plus facile que l’énumération des paramètres de commande et fonctionne sans révision, même si les paramètres de la commande appelée changent.
La fonctionnalité utilise la $Args
variable automatique, qui contient toutes les valeurs de paramètre non attribuées.
Par exemple, la fonction suivante appelle l’applet de Get-Process
commande. Dans cette fonction, @Args
représente tous les paramètres de l’applet Get-Process
de commande.
function Get-MyProcess { Get-Process @Args }
Lorsque vous utilisez la Get-MyProcess
fonction, tous les paramètres et valeurs de paramètres non attribués sont passés à @Args
, comme indiqué dans les commandes suivantes.
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\...
Vous pouvez utiliser @Args
dans une fonction qui a déclaré explicitement des paramètres. Vous pouvez l’utiliser plusieurs fois dans une fonction, mais tous les paramètres que vous entrez sont passés à toutes les instances de @Args
, comme illustré dans l’exemple suivant.
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)
Notes
Si vous définissez une fonction en fonction avancée à l’aide des attributs CmdletBinding ou Parameter , la $args
variable automatique n’est plus disponible dans la fonction. Les fonctions avancées nécessitent une définition de paramètre explicite.
PowerShell Desired State Configuration (DSC) n’a pas été conçu pour utiliser la plaque. Vous ne pouvez pas utiliser la mise en forme pour transmettre des valeurs à une ressource DSC. Pour plus d’informations, consultez l’article de Gael Colas Pseudo-Splatting DSC Resources.