about_Splatting
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0
TÓPICO
about_Splatting
DESCRIÇÃO BREVE
Descreve como usar o nivelamento para passar parâmetros para os comandos no Windows PowerShell®.
DESCRIÇÃO LONGA
[Este tópico foi uma contribuição de Rohn Edwards de Gulfport, Mississippi, um administrador de sistemas e o vencedor da categoria Advanced Division do 2012 Scripting Games. Revisado para Windows PowerShell 3.0.]
O nivelamento é um método de passagem de uma coleção de valores de parâmetro para um comando como unidade. O Windows PowerShell associa cada valor na coleção com um parâmetro de comando. Os valores de parâmetro nivelados são armazenados em variáveis de nivelamento nomeadas, que parecem variáveis padrão, mas que começam com uma arroba (@), em vez de um cifrão ($). A arroba diz ao Windows PowerShell que você está passando uma coleção de valores, em vez de um único valor.
O nivelamento faz com que os comandos fiquem mais curtos e fáceis de ler. Você pode reutilizar os valores de nivelamento em chamadas de comando diferentes e usar o nivelamento para passar valores de parâmetro da variável automática $PSBoundParameters para outros scripts e funções.
A partir do Windows PowerShell 3.0, você também pode usar o nivelamento para representar todos os parâmetros de um comando.
SINTAXE
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Para fornecer valores de parâmetro para parâmetros posicionais, nos quais os nomes de parâmetro não são necessários, use a sintaxe de matriz. Para fornecer pares de nome e valor de parâmetro, use a sintaxe da tabela de hash. O valor nivelado pode aparecer em qualquer lugar na lista de parâmetros.
Ao nivelar, você não precisa usar uma tabela de hash ou uma matriz para passar todos os parâmetros. Você pode passar alguns parâmetros usando o nivelamento e passar outros pela posição ou pelo nome do parâmetro. Além disso, você pode nivelar vários objetos em um único comando para passar não mais de um valor para cada parâmetro.
NIVELAMENTO COM TABELAS DE HASH
Use uma tabela de hash para nivelar pares de valor e nome de parâmetro. Você pode usar esse formato para todos os tipos de parâmetro, incluindo parâmetros nomeados e posicionais e parâmetros de opção.
Os exemplos a seguir comparam dois comandos Copy-Item que copiam o arquivo Test.txt no arquivo Test2.txt no mesmo diretório.
O primeiro exemplo usa o formato tradicional no qual os nomes de parâmetro estão incluídos.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
O segundo exemplo usa o nivelamento da tabela de hash. O primeiro comando cria uma tabela de hash dos pares de nome do parâmetro e valor do parâmetro e a armazena na variável $HashArguments. O segundo comando usa a variável $HashArguments em um comando com nivelamento. A arroba (@HashArguments) substitui o cifrão ($HashArguments) no comando.
Para fornecer um valor para o parâmetro de opção WhatIf, use $True ou $False.
PS C:\>$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
PS C:\>Copy-Item @HashArguments
Observação: No primeiro comando, a arroba (@) indica uma tabela de hash, não um valor nivelado. A sintaxe para tabelas de hash no Windows PowerShell é: @{ <nome>=<valor>; <nome>=<valor>; …}
NIVELAMENTO COM MATRIZES
Use uma matriz para nivelar valores para parâmetros posicionais, que não exigem nomes de parâmetro. Os valores devem estar na ordem do número da posição na matriz.
Os exemplos a seguir comparam dois comandos Copy-Item que copiam o arquivo Test.txt no arquivo Test2.txt no mesmo diretório.
O primeiro exemplo usa o formato tradicional no qual os nomes de parâmetro estão omitidos. Os valores de parâmetros aparecem na ordem da posição no comando.
Copy-Item "test.txt" "test2.txt" -WhatIf
O segundo exemplo usa o nivelamento de matriz. O primeiro comando cria uma matriz de valores de parâmetro e a armazena na variável $ArrayArguments. Os valores estão na ordem da posição na matriz. O segundo comando usa a variável $ArrayArguments em um comando no nivelamento. A arroba (@HashArguments) substitui o cifrão ($ArrayArguments) no comando.
PS C:\>$ArrayArguments = "test.txt", "test2.txt"
PS C:\>Copy-Item @ArrayArguments -WhatIf
EXEMPLOS
Este exemplo mostra como reutilizar valores nivelados em comandos diferentes. Os comandos neste exemplo usam o cmdlet Write-Host para gravar mensagens no console do programa de host. Ele usa o nivelamento para especificar as cores do primeiro e segundo planos.
Para alterar as cores de todos os comandos, basta alterar o valor da variável $Colors.
O primeiro comando cria uma tabela de hash de nomes e valores de parâmetros e armazena a tabela de hash na variável $Colors.
$Colors = @{ForegroundColor = "black"
BackgroundColor = "white"}
Os segundo e terceiro comandos usam a variável $Colors para o nivelamento em um comando de Write-Host. Para usar a variável $Colors, substitua o cifrão ($Colors) por uma 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 exemplo mostra como encaminhar seus parâmetros para outros comandos usando o nivelamento e a variável automática $PSBoundParameters.
A variável automática $PSBoundParameters é um dicionário (System.Collections.Generic.Dictionary) que contém todos os nomes e valores de parâmetros que são usados quando um script ou uma função é executada.
No exemplo a seguir, usamos a variável $PSBoundParameters para encaminhar os valores de parâmetros passados para um script ou uma função da função Test2 para a função Test1. Ambas as chamadas para a função Test1 de Test2 usam o nivelamento.
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
PARÂMETROS DO COMANDO DE NIVELAMENTO
Você pode usar o nivelamento para representar os parâmetros de um comando. Essa técnica é útil quando você está criando uma função de proxy, ou seja, uma função que chama outro comando. Esse recurso é introduzido no Windows PowerShell 3.0.
Para nivelar os parâmetros de um comando, use @Args para representar os parâmetros de comando. Essa técnica é mais fácil do que enumerar os parâmetros do comando e funciona sem revisão mesmo se os parâmetros do comando chamado mudarem.
O recurso usa a variável automática $Args, que contém todos os valores de parâmetro não atribuídos. Insira o corpo da seção aqui.
Por exemplo, a função a seguir chama o cmdlet Get-Process. Nessa função, @Args representa todos os parâmetros do cmdlet Get-Process.
function Get-MyProcess { Get-Process @Args }
Quando você usa a função Get-MyProcess, todos os parâmetros não atribuídos e os valores de parâmetro são passados para @Args, como mostrado nos comandos a seguir.
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
Você pode usar @Args em uma função que tenha parâmetros declarados explicitamente. Você pode usá-lo mais de uma vez em uma função, mas todos os parâmetros inseridos são passados para todas as instâncias de @Args, como mostrado no exemplo a seguir.
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
CONSULTE TAMBÉM
about_Arrays
about_Automatic_Variables
about_Hash_Tables
about_Parameters