about_Splatting

Artículo
01/30/2024

Descripción breve

Describe cómo usar la expansión para pasar parámetros a comandos en PowerShell.

Descripción larga

La expansión es un método para pasar una colección de valores de parámetro a un comando como una unidad. PowerShell asocia cada valor de la colección con un parámetro de comando. Los valores de parámetros de la placa se almacenan en variables de expansión con nombre, que tienen un aspecto similar a las variables estándar, pero comienzan con un símbolo At (@) en lugar de un signo de dólar ($). El símbolo At indica a PowerShell que está pasando una colección de valores, en lugar de un solo valor.

La expansión hace que los comandos sean más cortos y fáciles de leer. Puede reutilizar los valores de expansión en diferentes llamadas de comando y usar la expansión para pasar valores de parámetro de la $PSBoundParameters variable automática a otros scripts y funciones.

A partir de Windows PowerShell 3.0, también puede usar la expansión para representar todos los parámetros de un comando.

Sintaxis

<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>

Para proporcionar valores de parámetro para parámetros posicionales, en los que no se requieren nombres de parámetro, use la sintaxis de matriz. Para proporcionar pares de nombre de parámetro y valor, use la sintaxis de la tabla hash. El valor de la placa puede aparecer en cualquier parte de la lista de parámetros.

Al escalar, no es necesario usar una tabla hash ni una matriz para pasar todos los parámetros. Puede pasar algunos parámetros mediante la expansión y pasar otros por posición o por nombre de parámetro. Además, puedeplatar varios objetos en un solo comando para que no pase más de un valor para cada parámetro.

A partir de PowerShell 7.1, puede invalidar un parámetro de expansión definiendo explícitamente un parámetro en un comando.

Expansión con tablas hash

Use una tabla hash para asignar pares de nombre de parámetro y valor. Puede usar este formato para todos los tipos de parámetros, incluidos los parámetros posicionales y switch. Los parámetros posicionales deben asignarse por nombre.

En los ejemplos siguientes se comparan dos Copy-Item comandos que copian el archivo Test.txt en el archivo Test2.txt del mismo directorio.

En el primer ejemplo se usa el formato tradicional en el que se incluyen los nombres de parámetro.

Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf

En el segundo ejemplo se usa la expansión de tablas hash. El primer comando crea una tabla hash de pares parameter-name y parameter-value y la almacena en la $HashArguments variable . El segundo comando usa la $HashArguments variable en un comando con expansión. El símbolo At (@HashArguments) reemplaza el signo de dólar ($HashArguments) en el comando .

Para proporcionar un valor para el parámetro del modificador WhatIf , use $True o $False.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
  WhatIf = $true
}
Copy-Item @HashArguments

Nota:

En el primer comando, el símbolo At (@) indica una tabla hash, no un valor de placa. La sintaxis de las tablas hash en PowerShell es: @{<name>=<value>; <name>=<value>; ...}

Expansión con matrices

Use una matriz para splat values for positional parameters (Valores de placa para parámetros posicionales), que no requieren nombres de parámetro. Los valores deben estar en orden de posición en la matriz.

En los ejemplos siguientes se comparan dos Copy-Item comandos que copian el archivo Test.txt en el archivo Test2.txt del mismo directorio.

En el primer ejemplo se usa el formato tradicional en el que se omiten los nombres de parámetro. Los valores de parámetro aparecen en orden de posición en el comando .

Copy-Item "test.txt" "test2.txt" -WhatIf

En el segundo ejemplo se usa la expansión de matrices. El primer comando crea una matriz de los valores de parámetro y la almacena en la $ArrayArguments variable . Los valores están en orden de posición en la matriz. El segundo comando usa la $ArrayArguments variable en un comando en la expansión. El símbolo At (@ArrayArguments) reemplaza el signo de dólar ($ArrayArguments) en el comando .

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf

Uso del parámetro ArgumentList

Varios cmdlets tienen un parámetro ArgumentList que se usa para pasar valores de parámetro a un bloque de script ejecutado por el cmdlet . El parámetro ArgumentList toma una matriz de valores que se pasa al bloque de script. PowerShell usa eficazmente la expansión de matriz para enlazar los valores a los parámetros del bloque de script. Al usar ArgumentList, si necesita pasar una matriz como un único objeto enlazado a un único parámetro, debe encapsular la matriz como el único elemento de otra matriz.

El ejemplo siguiente tiene un bloque de script que toma un único parámetro que es una matriz de cadenas.

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
  } -ArgumentList $array

En este ejemplo, solo se pasa el primer elemento de $array al bloque de script.

Hello

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)

En este ejemplo, $array se ajusta en una matriz para que toda la matriz se pase al bloque de script como un solo objeto.

Hello World!

Ejemplos

Ejemplo 1: Reutilización de parámetros de placa en distintos comandos

En este ejemplo se muestra cómo reutilizar los valores de expansión en distintos comandos. Los comandos de este ejemplo usan el Write-Host cmdlet para escribir mensajes en la consola del programa host. Usa la expansión para especificar los colores de primer plano y de fondo.

Para cambiar los colores de todos los comandos, solo tiene que cambiar el valor de la $Colors variable.

El primer comando crea una tabla hash de nombres y valores de parámetros y almacena la tabla hash en la $Colors variable.

$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}

Los comandos segundo y tercero usan la $Colors variable para la expansión en un Write-Host comando. Para usar $Colors variable, reemplace el signo de dólar ($Colors) por un símbolo 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."

Ejemplo 2: Reenvío de parámetros mediante $PSBoundParameters

En este ejemplo se muestra cómo reenviar sus parámetros a otros comandos mediante la expansión y la $PSBoundParameters variable automática.

La $PSBoundParameters variable automática es un objeto de diccionario (System.Collections.Generic.Dictionary) que contiene todos los nombres y valores de parámetro que se usan cuando se ejecuta un script o una función.

En el ejemplo siguiente, usamos la $PSBoundParameters variable para reenviar los valores de parámetros pasados a un script o función de Test2 la función a la Test1 función. Ambas llamadas a la Test1 función desde Test2 usan la expansión.

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

Ejemplo 3: Invalidación de parámetros con parámetros definidos explícitamente

En este ejemplo se muestra cómo invalidar un parámetro con parámetros definidos explícitamente. Esto resulta útil cuando no desea crear una tabla hash nueva o cambiar un valor en la tabla hash que está usando para la plataforma.

La $commonParams variable almacena los parámetros para crear máquinas virtuales en la East US ubicación. La $allVms variable es una lista de máquinas virtuales que se van a crear. Recorremos la lista y usamos $commonParams para crear los parámetros para crear cada máquina virtual. Sin embargo, queremos myVM2 crearlo en una región diferente de las otras máquinas virtuales. En lugar de ajustar la $commonParams tabla hash, puede definir explícitamente el parámetro Location en New-AzVm para reemplazar el valor de la Location clave en $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
    }
}

Ejemplo 4: Uso de varios objetos de placa en un solo comando

Puede usar varios objetos de placa en un solo comando. En este ejemplo, se definen distintos parámetros en tablas hash independientes. Las tablas hash se dividen en un solo Write-Host comando.

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

Parámetros de comando de expansión

Puede usar la expansión para representar los parámetros de un comando. Esta técnica es útil cuando se crea una función de proxy, es decir, una función que llama a otro comando. Esta característica se presenta en Windows PowerShell 3.0.

Para expandir los parámetros de un comando, use @Args para representar los parámetros de comando. Esta técnica es más fácil que enumerar parámetros de comando y funciona sin revisión aunque los parámetros del comando llamado cambien.

La característica usa la $Args variable automática, que contiene todos los valores de parámetro sin asignar.

Por ejemplo, la función siguiente llama al Get-Process cmdlet . En esta función, @Args representa todos los parámetros del Get-Process cmdlet.

function Get-MyProcess { Get-Process @Args }

Cuando se usa la Get-MyProcess función , todos los parámetros sin asignar y los valores de parámetro se pasan a @Args, como se muestra en los comandos siguientes.

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\...

Puede usar @Args en una función que haya declarado explícitamente parámetros. Puede usarlo más de una vez en una función, pero todos los parámetros que escriba se pasan a todas las instancias de @Args, como se muestra en el ejemplo siguiente.

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)

Notas

Si crea una función en una función avanzada mediante los atributos CmdletBinding o Parameter , la $args variable automática ya no está disponible en la función. Las funciones avanzadas requieren una definición de parámetro explícita.

La configuración de estado deseado (DSC) de PowerShell no se diseñó para usar la expansión. No se puede usar la expansión para pasar valores a un recurso DSC. Para obtener más información, consulte el artículo de Gael Colas Pseudo-Splatting DSC Resources( Recursos de DSC de Gael Colas).