about_Splatting
Descrição breve
Descreve como usar o splatting para passar parâmetros para comandos no PowerShell.
Descrição longa
Splatting é um método de passar uma coleção de valores de parâmetro para um comando como uma unidade. O PowerShell associa cada valor na coleção a um parâmetro de comando. Os valores de parâmetro splatted são armazenados em variáveis splatting nomeadas, que se parecem com variáveis padrão, mas começam com um símbolo At (@) em vez de um cifrão ($). O símbolo At informa ao PowerShell que você está passando uma coleção de valores, em vez de um único valor.
O splatting torna seus comandos mais curtos e fáceis de ler. Você pode reutilizar os valores de splatting em diferentes chamadas de comando e usar o splatting para passar valores de parâmetro da $PSBoundParameters variável automática para outros scripts e funções.
A partir do Windows PowerShell 3.0, você também pode usar o splatting 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 espalhado pode aparecer em qualquer lugar na lista de parâmetros.
Ao fazer o splatting, 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 splatting e passar outros por posição ou por nome de parâmetro. Além disso, você pode splat vários objetos em um único comando para não passar mais de um valor para cada parâmetro.
A partir do PowerShell 7.1, você pode substituir um parâmetro espalhado definindo explicitamente um parâmetro em um comando.
Splatting com tabelas de hash
Use uma tabela de hash para splat de pares de nome e valor de parâmetro. Você pode usar esse formato para todos os tipos de parâmetros, incluindo parâmetros posicionais e de comutação. Os parâmetros posicionais devem ser atribuídos por nome.
Os exemplos a seguir comparam dois Copy-Item comandos que copiam o arquivo Test.txt para o arquivo Test2.txt no mesmo diretório.
O primeiro exemplo usa o formato tradicional no qual os nomes de parâmetros são incluídos.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
O segundo exemplo usa splatting de tabela de hash. O primeiro comando cria uma tabela de hash de pares de nome de parâmetro e valor de parâmetro e a armazena na $HashArguments variável. O segundo comando usa a $HashArguments variável em um comando com splatting. O símbolo de 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.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Observação
No primeiro comando, o símbolo At (@) indica uma tabela de hash, não um valor espalhado. A sintaxe para tabelas de hash no PowerShell é: @{<name>=<value>; <name>=<value>; ...}
Splatting com matrizes
Use uma matriz para splat de valores para parâmetros posicionais, que não exigem nomes de parâmetros. Os valores devem estar na ordem posição-número na matriz.
Os exemplos a seguir comparam dois Copy-Item comandos que copiam o arquivo Test.txt para o arquivo Test2.txt no mesmo diretório.
O primeiro exemplo usa o formato tradicional no qual os nomes de parâmetro são omitidos. Os valores dos parâmetros aparecem em ordem de posição no comando.
Copy-Item "test.txt" "test2.txt" -WhatIf
O segundo exemplo usa splatting de matriz. O primeiro comando cria uma matriz dos valores dos parâmetros e a armazena na $ArrayArguments variável. Os valores estão em ordem de posição na matriz. O segundo comando usa a $ArrayArguments variável em um comando em splatting. O símbolo de arroba (@ArrayArguments) substitui o cifrão ($ArrayArguments) no comando.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Usando o parâmetro ArgumentList
Vários cmdlets têm um parâmetro ArgumentList que é usado para passar valores de parâmetro para um bloco de script executado pelo cmdlet. O parâmetro ArgumentList usa uma matriz de valores que é passada para o bloco de script. O PowerShell está usando efetivamente o splatting de matriz para associar os valores aos parâmetros do bloco de script. Ao usar ArgumentList, se você precisar passar uma matriz como um único objeto associado a um único parâmetro, deverá encapsular a matriz como o único elemento de outra matriz.
O exemplo a seguir tem um bloco de script que usa um único parâmetro que é uma matriz de cadeias de caracteres.
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList $array
Neste exemplo, apenas o primeiro item é $array passado para o bloco de script.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
Neste exemplo, $array é encapsulado em uma matriz para que toda a matriz seja passada para o bloco de script como um único objeto.
Hello World!
Exemplos
Exemplo 1: Reutilizar parâmetros recortados em comandos diferentes
Este exemplo mostra como reutilizar valores replatados em diferentes comandos. Os comandos neste exemplo usam o Write-Host cmdlet para gravar mensagens no console do programa host. Ele usa splatting para especificar as cores do primeiro plano e do plano de fundo.
Para alterar as cores de todos os comandos, basta alterar o valor da $Colors variável.
O primeiro comando cria uma tabela de hash de nomes e valores de parâmetros e armazena a $Colors tabela de hash na variável.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
O segundo e o terceiro comandos usam a $Colors variável para splatting em um Write-Host comando. Para usar o , substitua o cifrão ($Colors) por um símbolo de arroba $Colors variable(@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."
Exemplo 2: Encaminhar parâmetros usando $PSBoundParameters
Este exemplo mostra como encaminhar seus parâmetros para outros comandos usando splatting e a $PSBoundParameters variável automática.
A $PSBoundParameters variável automática é um objeto de dicionário (System.Collections.Generic.Dictionary) que contém todos os nomes e valores de parâmetro usados quando um script ou função é executado.
No exemplo a seguir, 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 usar splatting.
function Test1
{
param($a, $b, $c)
"a = $a"
"b = $b"
"c = $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
Test1 -b $PSBoundParameters.b -c $PSBoundParameters.c
}
Test2 -a 1 -b 2 -c 3
a = 1
b = 2
c = 3
a =
b = 2
c = 3
Exemplo 3: Substituir parâmetros espalhados por parâmetros definidos explicitamente
Este exemplo mostra como substituir um parâmetro splatted usando parâmetros definidos explicitamente. Isso é útil quando você não deseja criar uma nova tabela de hash ou alterar um valor na tabela de hash que está usando para splat.
A $commonParams variável armazena os parâmetros para criar máquinas virtuais no East US local. A $allVms variável é uma lista de máquinas virtuais a serem criadas. Percorremos a lista e usamos $commonParams para espalhar os parâmetros para criar cada máquina virtual. No entanto, queremos myVM2 ser criados em uma região diferente das outras máquinas virtuais. Em vez de ajustar a $commonParams tabela de hash, você pode definir explicitamente o parâmetro Location em New-AzVm para substituir o Location valor da chave em $commonParams.
$commonParams = @{
ResourceGroupName = "myResourceGroup"
Location = "East US"
VirtualNetworkName = "myVnet"
SubnetName = "mySubnet"
SecurityGroupName = "myNetworkSecurityGroup"
PublicIpAddressName = "myPublicIpAddress"
}
$allVms = @('myVM1','myVM2','myVM3',)
foreach ($vm in $allVms)
{
if ($vm -eq 'myVM2')
{
New-AzVm @commonParams -Name $vm -Location "West US"
}
else
{
New-AzVm @commonParams -Name $vm
}
}
Exemplo 4: Usando vários objetos espalhados em um único comando
Você pode usar vários objetos espalhados em um único comando. Neste exemplo, diferentes parâmetros são definidos em tabelas de hash separadas. As tabelas de hash são espalhadas em um único Write-Host comando.
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
Parâmetros do comando Splatting
Você pode usar o splatting para representar os parâmetros de um comando. Essa técnica é útil quando você está criando uma função proxy, ou seja, uma função que chama outro comando. Esse recurso é introduzido no Windows PowerShell 3.0.
Para splat os parâmetros de um comando, use @Args para representar os parâmetros do comando. Essa técnica é mais fácil do que enumerar parâmetros de comando e funciona sem revisão, mesmo que os parâmetros do comando chamado sejam alterados.
O recurso usa a $Args variável automática, que contém todos os valores de parâmetro não atribuídos.
Por exemplo, a função a seguir 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 você usa a Get-MyProcess função, todos os parâmetros e valores de parâmetro não atribuídos são passados para @Args, conforme mostrado nos comandos a seguir.
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\...
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 , conforme mostrado no exemplo a @Argsseguir.
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
Get-MyCommand -P -C -Name PowerShell
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
50 112.76 78.52 16.64 6880 1 powershell
Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Source : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Version : 10.0.22621.3085
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.22621.1 (WinBuild.160101.0800)
FileDescription: Windows PowerShell
Product: Microsoft® Windows® Operating System
ProductVersion: 10.0.22621.1
Debug: False
Patched: False
PreRelease: False
PrivateBuild: False
SpecialBuild: False
Language: English (United States)
Observações
Se você transformar uma função em uma função avançada usando os atributos CmdletBinding ou Parameter , a $args variável automática não estará mais disponível na função. As funções avançadas requerem definição explícita de parâmetros.
A DSC (Configuração de Estado Desejado) do PowerShell não foi projetada para usar respingos. Você não pode usar splatting para passar valores para um recurso DSC. Para obter mais informações, consulte o artigo de Gael Colas Recursos de DSC de pseudo-splatting.
