Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
DESCRIPTION COURTE
Décrit comment utiliser la technique de "splatting" pour passer des paramètres à des commandes dans PowerShell.
DESCRIPTION DÉTAILLÉE
[Ce sujet a été contribué par Rohn Edwards de Gulfport, Mississippi, administrateur système et vainqueur de la division avancée des Scripting Games 2012. Révisé pour Windows PowerShell 3.0.]
Le splatting est une méthode qui consiste à passer 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 de paramètres projetées sont stockées dans des variables de projection nommées, qui sont semblables aux variables standard à ceci près qu’elles commencent par un symbole arobase (@) et non un signe dollar ($). Le symbole At indique à PowerShell que vous transmettez une collection de valeurs, au lieu d’une seule valeur.
La projection rend vos commandes plus courtes et plus faciles à lire. Vous pouvez réutiliser les valeurs de splatting dans différents appels de commande et utiliser splatting pour transmettre les valeurs de paramètre de la $PSBoundParameters variable automatique à d’autres scripts et fonctions.
À partir 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 fournir des valeurs de paramètre pour les paramètres positionnels, dans lesquels 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 projetée peut apparaître n’importe où dans la liste des paramètres.
Lors de la projection, vous n’avez pas besoin d’utiliser une table de hachage ou un tableau pour transmettre tous les paramètres. Vous pouvez transmettre certains paramètres en utilisant la projection, et en transmettre d’autres par position ou nom de paramètre. En outre, vous pouvez placer plusieurs objets dans une seule commande afin de ne pas transmettre plus d’une valeur pour chaque paramètre.
ÉCLABOUSSAGE AVEC DES TABLES DE HACHAGE
Utilisez une table de hachage pour projeter les paires nom/valeur des paramètres. Vous pouvez utiliser ce format pour tous les types de paramètres, y compris les paramètres positionnels et switch. Les paramètres de position doivent être attribués par nom.
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 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 projection par table de hachage. La première commande crée une table de hachage de paires nom-paramètre et paramètre-valeur et la stocke dans la variable $HashArguments. La deuxième commande utilise la variable $HashArguments dans une commande avec projection. Le symbole At (@HashArguments) remplace le signe dollar ($HashArguments) dans la commande.
Pour fournir une valeur pour le paramètre WhatIf switch, utilisez $True ou $False.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Remarque : Dans la première commande, le symbole At (@) indique une table de hachage, et non une valeur splatted. La syntaxe des tables de hachage dans PowerShell est la suivante : @{\<name\>=\<value\>; \<name\>=\<value\>; ...}*
ÉCLABOUSSAGE AVEC DES MATRICES
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 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 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 une projection par tableau. La première commande crée un tableau des valeurs de paramètre et les stocke dans la variable $ArrayArguments. Les valeurs sont dans l’ordre de position dans le tableau. La deuxième commande utilise la variable $ArrayArguments dans une commande de projection. Le symbole At (@ArrayArguments) remplace le signe dollar ($ArrayArguments) dans la commande.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
EXEMPLES
Cet exemple montre comment réutiliser des valeurs splatted 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. La projection est utilisée 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 variable $Colors.
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 variable $Colors.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Les deuxième et troisième commandes utilisent la variable $Colors pour la projection dans une commande Write-Host. Pour utiliser le $Colors variable, 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."
Cet exemple montre comment transmettre leurs paramètres à d’autres commandes à l’aide de splatting et de la $PSBoundParameters variable automatique.
La variable automatique $PSBoundParameters est un objet de 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 variable $PSBoundParameters pour transférer les valeurs de paramètres passées à un script ou à une fonction de Test2 fonction à la fonction Test1. Les deux appels à la fonction Test1 depuis Test2 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
}
Test2 -a 1 -b 2 -c 3
1
2
3
2
3
PARAMÈTRES DE LA COMMANDE SPLATTING
Vous pouvez utiliser la projection 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.
Pour projeter les paramètres d’une commande, utilisez @Args pour représenter ces derniers. 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 variable automatique $Args, qui contient toutes les valeurs de paramètre non attribuées.
Par exemple, la fonction suivante appelle l’applet de commande Get-Process. Dans cette fonction, @Args représente tous les paramètres de l’applet de commande Get-Process.
function Get-MyProcess { Get-Process @Args }
Lorsque vous utilisez la fonction Get-MyProcess, 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)
REMARQUES
PowerShell Desired State Configuration (DSC) n’est pas compatible avec la projection. Vous ne pouvez pas utiliser la projection pour transmettre des valeurs dans une ressource DSC. Pour plus d’informations, consultez l’article de Gael Colas Pseudo-Splatting ressources DSC.