Acerca de la expansión
DESCRIPCIÓN BREVE
Describe cómo usar la expansión para pasar parámetros a comandos en PowerShell.
DESCRIPCIÓN LARGA
[Este tema fue aportado por Rohn Edwards de Gulfport, Mississippi, un administrador del sistema y el ganador de la División Avanzada de los Juegos de Scripting de 2012. Revisado para Windows PowerShell 3.0.]
La expansión es un método para pasar una colección de valores de parámetro a un comando como unidad. PowerShell asocia cada valor de la colección con un parámetro de comando. Los valores de parámetros de plataforma 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 volver a usar los valores de expansión en diferentes llamadas de comando y usar la expansión 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 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 la 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 parte de la lista de parámetros.
Al expandirse, 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.
EXPANSIÓN CON TABLAS HASH
Use una tabla hash paraplatar 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 los 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 de 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 plataforma. La sintaxis de las tablas hash en PowerShell es: @{\<name\>=\<value\>; \<name\>=\<value\>; ...}*
EXPANSIÓN CON MATRICES
Use una matriz para expandir los valores de los 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
EJEMPLOS
En este ejemplo se muestra cómo volver a usar 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, simplemente cambie 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."
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ámetros que se usan cuando se ejecuta un script o una función.
En el ejemplo siguiente, se usa 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 de Test2 usan la 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 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 los parámetros de comando y funciona sin revisión aunque cambien los parámetros del comando llamado.
La característica usa la $Args variable automática, que contiene todos los valores de parámetro sin asignar.
Por ejemplo, la siguiente función 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 tenga parámetros declarados explícitamente. Puede usarlo más de una vez en una función, pero todos los parámetros especificados 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
PowerShell Desired State Configuration (DSC) no se diseñó para usar la expansión. No se puede usar la expansión para pasar valores a un recurso de DSC. Para obtener más información, consulte el artículo de Gael Colas pseudo-Splatting DSC Resources (Recursos de DSC de expansión de Gael Colas).