about_Splatting

Descripción breve

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

Descripción larga

"Splatting" 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 los parámetros expandidos se almacenan en variables splatting con nombre, que se parecen 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 sus comandos sean más cortos y fáciles de leer. Puede reutilizar los valores de expansión en diferentes llamadas a comandos y utilizar splatting para pasar valores de parámetros de la variable automática $PSBoundParameters a otros scripts y funciones.

A partir de Windows PowerShell 3.0, también puede utilizar 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 expansión puede aparecer en cualquier lugar de la lista de parámetros.

Cuando se utiliza la expansión, no es necesario utilizar una tabla hash o una matriz para pasar todos los parámetros. Puede pasar algunos parámetros utilizando la expansión y pasar otros por posición o por nombre de parámetro. Además, puede expandir varios objetos en un único comando para no pasar más de un valor para cada parámetro.

A partir de PowerShell 7.1, puede anular un parámetro expandido definiendo explícitamente un parámetro en un comando.

Expansión con tablas hash

Utilice una tabla hash para expandir pares de nombre y valor de parámetro. 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 comandos Copy-Item 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

El segundo ejemplo utiliza expansión con tablas hash. El primer comando crea una tabla hash de pares parameter-name y parameter-value y la almacena en la variable $HashArguments. El segundo comando utiliza la variable $HashArguments 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 de conmutación WhatIf, utilice $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 expansión. La sintaxis de las tablas hash en PowerShell es: @{<name>=<value>; <name>=<value>; ...}

Expansión con matrices

Usa una matriz para expandir valores 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 comandos Copy-Item 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

El segundo ejemplo utiliza la expansión con matrices. El primer comando crea una matriz de los valores de parámetro y la almacena en la variable $ArrayArguments. Los valores están en orden de posición en la matriz. El segundo comando utiliza la variable $ArrayArguments de un comando en 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 utiliza para pasar valores de parámetros a un bloque de script que es ejecutado por el cmdlet. El parámetro ArgumentList toma una matriz de valores que se pasa al bloque de script. PowerShell está utilizando efectivamente expansión con matrices para vincular 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 encapsula en una matriz para que toda la matriz se pase al bloque de script como un solo objeto.

Hello World!

Ejemplos

Ejemplo 1: Reutilizar parámetros de expansión en diferentes comandos

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

Para cambiar los colores de todos los comandos, simplemente cambie el valor de la variable $Colors.

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

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

El segundo y tercer comando utilizan la variable $Colors para expandir en un comando Write-Host. Para usar el $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 el uso de splatting y la variante automática $PSBoundParameters.

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

En el ejemplo siguiente, usamos la variable $PSBoundParameters para reenviar los valores de parámetros pasados a un script o función de Test2 función a la función Test1. Ambas llamadas a la función Test1 de Test2 usan 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: Anular parámetros de expansión con parámetros

Este ejemplo muestra cómo anular un parámetro de expansión utilizando parámetros definidos explícitamente. Esto es útil cuando no se desea construir una nueva tabla hash o cambiar un valor en la tabla hash que se está utilizando para la expansión.

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

Puede utilizar varios objetos de expansión en un único comando. En este ejemplo, se definen distintos parámetros en tablas hash independientes. Las tablas de hash se expanden en un solo comando Write-Host.

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

Expansión de parámetros

Puede utilizar 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, utilice @Args para representar los parámetros del 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 cmdlet Get-Process. En esta función, @Args representa todos los parámetros del cmdlet Get-Process.

function Get-MyProcess { Get-Process @Args }

Cuando se usa la función Get-MyProcess, 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 convierte una función en una función avanzada mediante los atributos CmdletBinding o Parameter, la variable automática $args ya no está disponible en la función. Las funciones avanzadas requieren una definición de parámetro explícita.

Desired State Configuration (DSC) de PowerShell no se diseñó para utilizar la expansión. No puede utilizar 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.

Consulte también

Last updated on 2024-01-29

Compartir a través de