about_Splatting
Mis à jour: mai 2014
S'applique à: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
RUBRIQUE
about_Splatting
DESCRIPTION COURTE
Décrit comment utiliser la projection pour passer des paramètres à des commandes dans Windows PowerShell®.
DESCRIPTION DÉTAILLÉE
[Cette rubrique a été conçue avec l'aide de Rohn Edwards, un administrateur système de Gulfport (Mississippi) qui a remporté les Scripting Games de 2012 dans la catégorie Advanced Division. Elle a été mise à jour pour Windows PowerShell 3.0.]
La projection est une méthode consistant à passer une collection de valeurs de paramètre à une commande. Windows PowerShell associe chaque valeur dans la collection à un paramètre de commande. Les valeurs de paramètre projetées sont stockées dans des variables de projection nommées, qui ressemblent à des variables standard, mais commencent par le symbole arobase (@) au lieu du signe dollar ($). Le symbole arobase indique à Windows PowerShell que vous passez une collection de valeurs, et non une seule valeur.
Grâce à la projection, vos commandes sont plus courtes et plus faciles à lire. Vous pouvez réutiliser les valeurs de projection dans différents appels de commandes. La projection vous permet aussi de passer des valeurs de paramètre de la variable automatique $PSBoundParameters à d'autres scripts et fonctions.
À compter de Windows PowerShell 3.0, vous pouvez également utiliser la projection pour représenter tous les paramètres d'une commande.
SYNTAXE
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Pour spécifier les valeurs de paramètres positionnels, où les noms des paramètres sont facultatifs, utilisez la syntaxe de tableau. Pour spécifier les paires nom-valeur de paramètres, utilisez la syntaxe de table de hachage. La valeur projetée peut se trouver n'importe où dans la liste de paramètres.
Avec la projection, 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 projection et d'autres paramètres avec la position ou le nom de paramètre. Vous pouvez également projeter plusieurs objets dans une seule commande pour passer une seule valeur pour chaque paramètre.
PROJECTION AVEC UNE TABLE DE HACHAGE
Utilisez une table de hachage pour projeter les paires nom-valeur des paramètres. Ce format s'applique à tous les types de paramètres, y compris les paramètres nommés et positionnels ainsi que les paramètres booléens.
Les exemples suivants comparent deux commandes Copy-Item qui copient le fichier Test.txt dans le fichier Test2.txt dans le même répertoire.
Le premier exemple utilise le format standard qui inclut les noms des paramètres.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
Le deuxième exemple utilise la projection avec une table de hachage. La première commande crée une table de hachage des paires nom-valeur des paramètres, et stocke le résultat dans la variable $HashArguments. La deuxième commande utilise la variable $HashArguments dans une commande avec projection. Le symbole arobase (@HashArguments) remplace le signe dollar ($HashArguments) dans la commande.
Pour le paramètre booléen WhatIf, spécifiez la valeur $True ou $False.
PS C:\>$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
PS C:\>Copy-Item @HashArguments
Remarque : dans la première commande, le symbole arobase (@) indique qu'il s'agit d'une table de hachage, et non une valeur projetée. La syntaxe pour les tables de hachage dans Windows PowerShell est la suivante : @{ <name>=<value>; <name>=<value>; …}
PROJECTION AVEC DES TABLEAUX
Utilisez un tableau pour projeter les valeurs des paramètres positionnels, où les noms de paramètre sont facultatifs. Les valeurs doivent être spécifiées dans l'ordre du numéro de position dans le tableau.
Les exemples suivants comparent deux commandes Copy-Item qui copient le fichier Test.txt dans le fichier Test2.txt dans le même répertoire.
Le premier exemple utilise le format standard qui n'inclut pas les noms des paramètres. Les valeurs de paramètre s'affichent dans l'ordre de position dans la commande.
Copy-Item "test.txt" "test2.txt" -WhatIf
Le deuxième exemple utilise la projection avec un tableau. La première commande crée un tableau de valeurs de paramètre et le stocke dans la variable $ArrayArguments. Les valeurs sont spécifiées dans l'ordre de position dans le tableau. La deuxième commande utilise la variable $ArrayArguments dans une commande avec projection. Le symbole arobase (@ArrayArguments) remplace le signe dollar ($ArrayArguments) dans la commande.
PS C:\>$ArrayArguments = "test.txt", "test2.txt"
PS C:\>Copy-Item @ArrayArguments -WhatIf
EXEMPLES
Cet exemple montre comment réutiliser des valeurs projetées dans différentes commandes. Les commandes de cet exemple utilisent l'applet de commande Write-Host pour écrire des messages dans la console du programme hôte. Elles utilisent la projection pour spécifier les couleurs de premier plan et d'arrière-plan.
Pour changer les couleurs de toutes les commandes, modifiez simplement la valeur de la variable $Colors.
La première commande crée une table de hachage des paires nom-valeur des paramètres et la stocke dans la variable $Colors.
$Colors = @{ForegroundColor = "black"
BackgroundColor = "white"}
Les deuxième et troisième commandes utilisent la variable $Colors pour effectuer la projection dans une commande Write-Host. Pour utiliser la variable $Colors, remplacez le signe dollar ($Colors) par le symbole arobase (@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."
Cet exemple montre comment transmettre leurs paramètres à d'autres commandes à l'aide de la projection et de la variable automatique $PSBoundParameters.
La variable automatique $PSBoundParameters est un dictionnaire (System.Collections.Generic.Dictionary) qui contient l'ensemble des noms et valeurs de paramètre qui sont utilisés pendant l'exécution d'un script ou d'une fonction.
L'exemple suivant utilise la variable $PSBoundParameters pour transmettre les valeurs de paramètre passées à un script ou une fonction de la fonction Test2 à la fonction Test1. Les deux appels de Test2 à la fonction Test1 utilisent la projection.
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
}
PS C:\> Test2 -a 1 -b 2 -c 3
1
2
3
2
3
PROJECTION DES PARAMÈTRES D'UNE COMMANDE
Vous pouvez utiliser la projection pour représenter les paramètres d'une commande. Cette méthode est utile quand vous créez une fonction proxy, autrement dit, une fonction qui appelle une autre commande. Cette fonctionnalité a été introduite dans Windows PowerShell 3.0.
Pour projeter les paramètres d'une commande, utilisez la variable @Args pour représenter les paramètres de la commande. Cette méthode est plus simple que l'énumération des paramètres de commande. De plus, elle ne nécessite pas de modification, même si les paramètres de la commande appelée changent.
La fonctionnalité utilise la variable automatique $Args, qui contient toutes les valeurs de paramètre non assignées.Insérez le corps de la section ici.
Par exemple, la fonction suivante appelle l'applet de commande Get-Process. Dans cette fonction, @Args représente l'ensemble des paramètres de l'applet de commande Get-Process.
function Get-MyProcess { Get-Process @Args }
Quand vous utilisez la fonction Get-MyProcess, tous les paramètres et valeurs de paramètre non assignés sont passés à @Args, comme dans les commandes suivantes.
PS C:\> 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
PS C:\> Get-MyProcess -Name PowerShell_Ise -FileVersionInfo
ProductVersion FileVersion FileName
-------------- ----------- --------
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe
Vous pouvez utiliser @Args dans une fonction qui a déclaré explicitement les paramètres. Vous pouvez l'utiliser plusieurs fois dans une fonction, mais chaque paramètre que vous entrez est passé à toutes les instances de @Args, comme indiqué dans l'exemple suivant.
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
PS C:\> 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.exe
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
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
VOIR AUSSI
about_Arrays
about_Automatic_Variables
about_Hash_Tables
about_Parameters