Partager via

about_Splatting

Brève description

Décrit comment utiliser la technique de "splatting" pour passer des paramètres à des commandes dans PowerShell.

Description longue

La projection est une méthode permettant de transmettre une collection de valeurs de paramètres à une commande en tant qu’une 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 projection dans différents appels de commandes et utiliser la projection pour transmettre des valeurs de paramètres de la variable automatique $PSBoundParameters à 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 projeter plusieurs objets dans une seule commande afin de ne pas transmettre plus d’une valeur pour chaque paramètre.

À partir de PowerShell 7.1, vous pouvez outrepasser un paramètre éclaté en définissant explicitement un paramètre dans une commande.

Mise en forme 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, pas une valeur éclatée. La syntaxe des tables de hachage dans PowerShell est la suivante : @{<name>=<value>; <name>=<value>; ...}

Platissement 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 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

Utilisation du paramètre ArgumentList

Plusieurs applets de commande ont un paramètre ArgumentList utilisé pour passer des valeurs de paramètre à un scriptblock exécuté par l’applet de commande. Le paramètre ArgumentList prend un tableau de valeurs passées au scriptblock. PowerShell utilise efficacement la mise en forme de tableau pour lier les valeurs aux paramètres du scriptblock. Lorsque vous utilisez ArgumentList, si vous devez passer un tableau en tant qu’objet unique lié à un paramètre unique, vous devez encapsuler le tableau comme seul élément d’un autre tableau.

L’exemple suivant contient un scriptblock qui prend un paramètre unique 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 scriptblock.

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 scriptblock en tant qu’objet unique.

Hello World!

Examples

Exemple 1 : Réutiliser les paramètres projetés dans différentes commandes

Cet exemple montre comment réutiliser des valeurs éclaté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. 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."

Exemple 2 : Transférer des paramètres à l’aide de $PSBoundParameters

Cet exemple montre comment transférer les paramètres à d’autres commandes en utilisant la projection et la variable automatique $PSBoundParameters.

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 = $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

Exemple 3 : Remplacer les paramètres éclatés avec des paramètres définis explicitement

Cet exemple montre comment remplacer un paramètre projeté en utilisant des paramètres définis de manière explicite. Cela s’avère utile lorsque vous ne souhaitez pas créer une nouvelle table de hachage ou modifier une valeur de la table de hachage que vous utilisez pour la projection.

La variable $commonParams stocke les paramètres pour créer des machines virtuelles à l’emplacement East US. La variable $allVms est une liste de machines virtuelles à créer. Nous parcourons la liste en boucle et utilisons $commonParams pour projeter les paramètres afin de créer chaque machine virtuelle. Toutefois, nous voulons que myVM2 soit créé dans une région différente de celle des autres machines virtuelles. Au lieu d’ajuster la table de hachage $commonParams, vous pouvez définir explicitement le paramètre Location dans New-AzVm pour remplacer la valeur de la clé Location 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
    }
}

Exemple 4 : Utilisation de plusieurs objets éclatés dans une seule commande

Vous pouvez utiliser plusieurs objets splattés dans une seule commande. Dans cet exemple, différents paramètres sont définis dans des tables de hachage distinctes. Les tables de hachage sont projetées dans une seule commande Write-Host.

$a = @{
    Message         = 'Hello', 'World!'
}
$b = @{
    Separator       = '|'
}
$c = @{
    BackgroundColor = 'Cyan'
    ForegroundColor = 'Black'
}
Write-Host @a @b @c

Paramètres de commande de platissement

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

 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)

Remarques

Si vous placez une fonction dans une fonction avancée à l’aide du CmdletBinding ou des attributs Parameter, la variable automatique $args 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’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.

Voir aussi

  • Last updated on