Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
DESCRIPCIÓN BREVE
Describe cómo utilizar la expansión para pasar parámetros a comandos en PowerShell.
DESCRIPCIÓN LARGA
[Este tema fue contribuido por Rohn Edwards de Gulfport, Mississippi, administrador de sistemas y ganador de la División Avanzada de los Juegos de Scripting 2012. Revisado para Windows PowerShell 3.0.]
Splatting es un método para pasar una colección de valores de parámetros a un comando como 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 splatting en diferentes llamadas de comando y usar splatting para pasar valores de parámetros de la $PSBoundParameters variable automática 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 salpicar varios objetos en un solo comando para no pasar más de un valor para cada parámetro.
SPLATTING 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 del modificador 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 splatted. La sintaxis de las tablas hash en PowerShell es: @{\<name\>=\<value\>; \<name\>=\<value\>; ...}*
SALPICADO 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
EJEMPLOS
En este ejemplo se muestra cómo reutilizar valores salpicados en diferentes 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."
En este ejemplo se muestra cómo reenviar sus parámetros a otros comandos mediante el uso de splatting y la $PSBoundParameters variable automática.
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
$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
PARÁMETROS DEL COMANDO SPLATTING
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
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)
NOTAS
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.