about_Splatting
Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
TEMA
about_Splatting
DESCRIPCIÓN BREVE
Describe cómo usar el empaquetamiento para pasar parámetros a comandos en Windows PowerShell®.
DESCRIPCIÓN LARGA
[Este tema es una aportación de Rohn Edwards de Gulfport, Misisipi, un administrador de sistemas y ganador de Advanced Division de Scripting Games de 2012. Revisado para Windows PowerShell 3.0].
El empaquetamiento es un método para pasar una colección de valores de parámetros a un comando como unidad. Windows PowerShell asocia cada valor de la colección con un parámetro de comando. Los valores de parámetros empaquetados se almacenan en variables de empaquetamiento con nombre, que son similares a las variables estándar, pero comienzan con un símbolo de arroba (@) en lugar de un signo del dólar ($). El símbolo de arroba indica a Windows PowerShell que está pasando una colección de valores, en lugar de un solo valor.
El empaquetamiento hace que los sean comandos más cortos y fáciles de leer. Puede volver a usar los valores de empaquetamiento en diferentes llamadas de comandos y usar el empaquetamiento 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 usar el empaquetamiento 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ámetros para los parámetros posicionales, que no requieren nombres de parámetro, use la sintaxis de la matriz. Para proporcionar los pares de nombre y valor de los parámetros, use la sintaxis de la tabla hash. El valor empaquetado puede aparecer en cualquier lugar de la lista de parámetros.
Cuando se realiza empaquetamiento, no es necesario usar una tabla hash o una matriz para pasar todos los parámetros. Puede pasar algunos parámetros usando empaquetamiento y otros por posición o por nombre de parámetro. Además, puede empaquetar varios objetos en un único comando para no pasar más de un valor para cada parámetro.
EMPAQUETAMIENTO CON LAS TABLAS HASH
Use una tabla hash para empaquetar los pares de nombre y valor de los parámetros. Puede usar este formato para todos los tipos de parámetro, incluidos los parámetros posicionales, con nombre y los de modificador.
Los ejemplos siguientes comparan dos comandos Copy-Item que copian el archivo Test.txt en el archivo Test2.txt en el mismo directorio.
El primer ejemplo 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 usa el empaquetamiento de tabla hash. El primer comando crea una tabla hash de pares de nombre de parámetro y valor de parámetro y la almacena en la variable $HashArguments. El segundo comando usa la variable $HashArguments en un comando con empaquetamiento. El símbolo de arroba (@HashArguments) reemplaza al signo del dólar ($HashArguments) en el comando.
Para proporcionar un valor para el parámetro de modificador WhatIf, use $True o $False.
PS C:\>$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
PS C:\>Copy-Item @HashArguments
Nota: En el primer comando, al símbolo de arroba (@) indica una tabla hash, no un valor empaquetado. La sintaxis de las tablas hash de Windows PowerShell es: @{ <name>=<value>; <name>=<value>; …}
EMPAQUETAMIENTO CON MATRICES
Use una matriz para empaquetar valores para parámetros posicionales, que no requieren nombres de parámetro. Los valores deben estar en orden de número de posición en la matriz.
Los ejemplos siguientes comparan dos comandos Copy-Item que copian el archivo Test.txt en el archivo Test2.txt en el mismo directorio.
El primer ejemplo usa el formato tradicional, en el que se omiten los nombres de parámetro. Los valores de parámetros aparecen en orden de posición en el comando.
Copy-Item "test.txt" "test2.txt" -WhatIf
El segundo ejemplo usa el empaquetamiento de matriz. El primer comando crea una matriz de los valores de parámetros y la almacena en la variable $ArrayArguments. Los valores están en orden de posición en la matriz. El segundo comando usa la variable $ArrayArguments en un comando en empaquetamiento. El símbolo de arroba (@ArrayArguments) reemplaza al signo del dólar ($ArrayArguments) en el comando.
PS C:\>$ArrayArguments = "test.txt", "test2.txt"
PS C:\>Copy-Item @ArrayArguments -WhatIf
EJEMPLOS
Este ejemplo muestra cómo volver a usar los valores empaquetados en diferentes comandos. Los comandos de este ejemplo usan el cmdlet Write-Host para escribir mensajes en la consola del programa host. Usa el empaquetamiento para especificar los colores de primer plano y de fondo.
Para cambiar los colores de todos los comandos, solo debe cambiar el valor de la variable $Colors.
El primer comando crea una tabla hash de los nombres y valores de parámetro y almacena la tabla hash en la variable $Colors.
$Colors = @{ForegroundColor = "black"
BackgroundColor = "white"}
El segundo y tercer comando usan la variable $Colors para realizar el empaquetamiento en un comando de Write-Host. Para usar la variable $Colors, reemplace el signo del dólar ($Colors) con un símbolo de arroba (@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."
Este ejemplo muestra cómo enviar sus parámetros a otros comandos mediante empaquetamiento y la variable automática $PSBoundParameters.
La variable automática $PSBoundParameters es un 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 se usa la variable $PSBoundParameters para reenviar los valores de parámetros que se pasan a un script o una función de la función Test2 a la función Test1. Las dos llamadas a la función Test1 desde Test2 usan empaquetamiento.
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
EMPAQUETAMIENTO DE PARÁMETROS DE COMANDOS
Puede usar el empaquetamiento para representar los parámetros de un comando. Esta técnica es útil cuando se crea una función de servidor proxy, es decir, una función que llama a otro comando. Esta característica se introdujo en Windows PowerShell 3.0.
Para empaquetar los parámetros de un comando, use @Args para representar los parámetros del comando. Esta técnica es más sencilla que enumerar los parámetros del comando y funciona sin revisión incluso aunque cambien los parámetros del comando al que se llama.
Esta característica usa la variable automática $Args, que contiene todos los valores de parámetro sin asignar. Insertar aquí el cuerpo de la sección.
Por ejemplo, la siguiente función 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 los parámetros se pasan a @Args, como se muestra en los siguientes comandos.
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
Puede usar @Args en una función que tiene parámetros declarados explícitamente. Puede usarla más de una vez en una función, pero todos los parámetros que especifique 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 }
}
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
VEA TAMBIÉN
about_Arrays
about_Automatic_Variables
about_Hash_Tables
about_Parameters