Sobre splatting
BREVE DESCRIÇÃO
Descreve como usar a splatting para passar parâmetros para comandos em PowerShell.
LONGA DESCRIÇÃO
[Este tópico foi contribuído por Rohn Edwards de Gulfport, Mississippi, um administrador do sistema e vencedor da Divisão Avançada dos Jogos de Scripting de 2012. Revisto para Windows PowerShell 3.0.]
Splatting é um método de passar uma coleção de valores de parâmetros para um comando como unidade. A PowerShell associa cada valor da coleção a um parâmetro de comando. Os valores dos parâmetros splatted são armazenados em variáveis de salpicos nomeadas, que parecem variáveis padrão, mas começam com um símbolo At @ () em vez de um sinal de dólar ( $ ). O símbolo At diz ao PowerShell que está a passar uma coleção de valores, em vez de um único valor.
A splatting torna os seus comandos mais curtos e fáceis de ler. Pode reutilizar os valores de salpicos em diferentes chamadas de comando e utilizar a splatting para passar os valores dos parâmetros da $PSBoundParameters variável automática para outras scripts e funções.
A partir do Windows PowerShell 3.0, também pode utilizar salpicos 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âmetros para parâmetros posicionais, nos quais não são necessários nomes de parâmetros, utilize a sintaxe da matriz. Para fornecer o nome do parâmetro e os pares de valor, utilize a sintaxe da tabela de haxixe. O valor splatted pode aparecer em qualquer lugar da lista de parâmetros.
Ao salpicar, não é necessário utilizar uma mesa de haxixe ou uma matriz para passar todos os parâmetros. Pode passar alguns parâmetros utilizando salpicos e passar outros por posição ou por nome de parâmetro. Além disso, pode splat vários objetos num único comando apenas para que não passe mais do que um valor para cada parâmetro.
SALPICOS COM MESAS DE HAXIXE
Use uma mesa de haxixe para splat nome de parâmetro e pares de valor. Pode utilizar este formato para todos os tipos de parâmetros, incluindo parâmetros posicionais e comutadores. Os parâmetros posicionais devem ser atribuídos pelo nome.
Os exemplos a seguir comparam dois Copy-Item comandos que copiam o ficheiro Test.txt ao ficheiro Test2.txt no mesmo diretório.
O primeiro exemplo utiliza o formato tradicional em que os nomes dos parâmetros estão incluídos.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
O segundo exemplo utiliza salpicos de mesa de haxixe. O primeiro comando cria uma tabela de haxixe de pares de parâmetros e valor de parâmetros e armazena-o na $HashArguments variável. O segundo comando utiliza a $HashArguments variável num comando com salpicos. O símbolo At ( @HashArguments ) substitui o sinal de dólar ( ) no $HashArguments comando.
Para fornecer um valor para o parâmetro de comutação WhatIf, utilize $True ou $False .
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Nota: No primeiro comando, o símbolo At (@) indica uma tabela hash, não um valor splatted. A sintaxe para tabelas de haxixe no PowerShell é:@{\<name\>=\<value\>; \<name\>=\<value\>; ...}*
SALPICANDO COM MATRIZES
Utilize uma matriz para splat valores para parâmetros posicionais, que não requerem nomes de parâmetros. Os valores devem estar na ordem do número de posição na matriz.
Os exemplos a seguir comparam dois Copy-Item comandos que copiam o ficheiro Test.txt ao ficheiro Test2.txt no mesmo diretório.
O primeiro exemplo utiliza o formato tradicional em que os nomes dos parâmetros são omitidos. Os valores dos parâmetros aparecem na ordem de posição no comando.
Copy-Item "test.txt" "test2.txt" -WhatIf
O segundo exemplo utiliza a chapa de matriz. O primeiro comando cria uma matriz dos valores dos parâmetros e armazena-o na $ArrayArguments variável. Os valores estão em ordem de posição na matriz. O segundo comando usa a $ArrayArguments variável num comando em splatting. O símbolo At ( @ArrayArguments ) substitui o sinal de dólar ( ) no $ArrayArguments comando.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
EXEMPLOS
Este exemplo mostra como reutilizar valores splatted em diferentes comandos. Os comandos neste exemplo usam o Write-Host cmdlet para escrever mensagens na consola do programa anfitrião. Usa salpicos para especificar as cores de primeiro plano e de fundo.
Para mudar as cores de todos os comandos, basta alterar o valor da $Colors variável.
O primeiro comando cria uma tabela de haxixe de nomes e valores de parâmetros e armazena a tabela de haxixe na $Colors variável.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Os segundos e terceiros comandos utilizam a $Colors variável para salpicos num Write-Host comando. Para utilizar o $Colors variable sinal , substitua o sinal de dólar ( $Colors ) com um 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."
Este exemplo mostra como encaminhar os seus parâmetros para outros comandos utilizando salpicos e a $PSBoundParameters variável automática.
A $PSBoundParameters variável automática é um objeto dicionário (System.Collections.Generic.Dictionary) que contém todos os nomes e valores dos parâmetros que são usados quando um script ou função é executado.
No exemplo seguinte, usamos a $PSBoundParameters variável para encaminhar os valores dos parâmetros passados para um script ou função da Test2 função para a Test1 função. Ambas as chamadas para a Test1 função de Test2 utilização de salpicos.
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 SPLATTING
Pode utilizar a splatting para representar os parâmetros de um comando. Esta técnica é útil quando se está a criar uma função de procuração, isto é, uma função que chama outro comando. Esta funcionalidade é introduzida no Windows PowerShell 3.0.
Para splat os parâmetros de um comando, use @Args para representar os parâmetros de comando. Esta técnica é mais fácil do que enumerar parâmetros de comando e funciona sem revisão, mesmo que os parâmetros da chamada mudança de comando.
A função utiliza a $Args variável automática, que contém todos os valores de parâmetros não atribuídos.
Por exemplo, a seguinte função chama o Get-Process cmdlet. Nesta função, @Args representa todos os parâmetros do Get-Process cmdlet.
function Get-MyProcess { Get-Process @Args }
Quando utiliza a Get-MyProcess função, todos os parâmetros e valores de parâmetros não atribuídos são passados para @Args , como mostrado nos seguintes comandos.
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\...
Pode utilizar @Args numa função que tenha explicitamente declarado parâmetros. Pode usá-lo mais do que uma vez numa função, mas todos os parâmetros que introduz são passados para todos os casos de @Args , como mostra o exemplo seguinte.
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
A configuração do estado desejado por PowerShell (DSC) não foi concebida para utilizar salpicos. Não é possível utilizar a splatting para passar valores num recurso DSC. Para mais informações, consulte o artigo pseudo-Splatting DSC Resources de Gael Colas.