about_Splatting
Descreve como usar o fracionamento para passar parâmetros para comandos no PowerShell.
Fracionamento é um método para passar uma coleção de valores de parâmetros 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 fracionados são armazenados em variáveis de fracionamento nomeadas, que se parecem com variáveis padrão, mas começam com um símbolo At (@) em vez de um sinal de dólar ($). O símbolo At informa ao PowerShell que você está passando uma coleção de valores, em vez de um único valor.
O fracionamento torna seus comandos mais curtos e fáceis de ler. Você pode reutilizar os valores de fracionamento em diferentes chamadas de comando e usar o fracionamento 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 fracionamento para representar todos os parâmetros de um comando.
<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 da matriz. Para fornecer pares de nome e valor de parâmetro, use a sintaxe da tabela de hash. O valor fracionado pode aparecer em qualquer posição na lista de parâmetros.
Ao usar fracionamento, 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 fracionamento e passar outros por posição ou pelo nome do parâmetro. Além disso, você pode espalhar vários objetos em um único comando para não passar mais de um valor por parâmetro.
A partir do PowerShell 7.1, você pode substituir um parâmetro fracionado definindo explicitamente um parâmetro em um comando.
Use uma tabela de hash para espalhar os pares de nome e valor de parâmetro. Você pode usar esse formato para todos os tipos de parâmetro, incluindo parâmetros posicionais e comutadores. Os parâmetros posicionais devem ser atribuídos pelo nome.
Os exemplos a seguir comparam dois comandos Copy-Item 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 incluídos.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
O segundo exemplo usa o recurso de fracionamento em uma tabela de hash. O primeiro comando cria uma tabela de hash de pares parâmetro-nome e parâmetro-valor e armazena-a na variável $HashArguments. O segundo comando usa a variável $HashArguments em um comando com fracionamento. O símbolo At (@HashArguments) substitui o sinal de dólar ($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 fracionado. A sintaxe das tabelas de hash no PowerShell é: @{<name>=<value>; <name>=<value>; ...}
Use uma matriz para unir valores para parâmetros posicionais, que não exigem nomes de parâmetro. Os valores devem estar em ordem de número de posição na matriz.
Os exemplos a seguir comparam dois comandos Copy-Item 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 de parâmetro aparecem na ordem de posição no comando.
Copy-Item "test.txt" "test2.txt" -WhatIf
O segundo exemplo usa fracionamento de matriz. O primeiro comando cria uma matriz dos valores de parâmetro e o armazena na variável $ArrayArguments. Os valores estão em ordem de posição na matriz. O segundo comando usa a variável $ArrayArguments em um comando no fracionamento. O símbolo At (@ArrayArguments) substitui o sinal de dólar ($ArrayArguments) no comando.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Vários cmdlets têm um parâmetro ArgumentList 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á efetivamente usando o fracionamento 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, somente o primeiro item em $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!
Este exemplo mostra como reutilizar valores fracionados em comandos diferentes. Os comandos neste exemplo usam o cmdlet Write-Host para gravar mensagens no console do programa host. Ele usa o fracionamento para especificar as cores de primeiro plano e em segundo plano.
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 valores e nomes de parâmetro e armazena a tabela de hash na variável $Colors.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
O segundo e o terceiro comandos usam a variável $Colors para fracionamento em um Write-Host comando. Para usar o $Colors variable, substitua o sinal de dólar ($Colors) por 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 parâmetros para outros comandos usando o fracionamento e o $PSBoundParameters, a variável automática.
A variável $PSBoundParameters 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 variável $PSBoundParameters para encaminhar os valores de parâmetros passados para um script ou função de Test2 função para a função Test1. Ambas as chamadas para a função Test1 de Test2 usam o fracionamento.
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
Este exemplo mostra como substituir um parâmetro fracionado 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 você está usando para fracionar.
A variável $commonParams armazena os parâmetros para criar máquinas virtuais no local East US. A variável $allVms é uma lista de máquinas virtuais a serem criadas. Percorremos a lista e usamos $commonParams para expandir os parâmetros e criar cada máquina virtual. No entanto, queremos que myVM2 sejam criados em uma região diferente das outras máquinas virtuais. Em vez de ajustar o hashtable de $commonParams, você pode definir explicitamente o parâmetro Location em New-AzVm para substituir o valor da chave Location 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
}
}
Você pode usar vários objetos fracionados em um único comando. Neste exemplo, parâmetros diferentes são definidos em hashables separados. As tabelas hash são distribuídas em um único comando Write-Host.
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
Você pode usar o fracionamento 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 expandir 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 se os parâmetros do comando chamado forem alterados.
O recurso usa a variável automática $Args, que contém todos os valores de parâmetro não atribuídos.
Por exemplo, a função a seguir chama o cmdlet Get-Process. Nesta 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 valores de parâmetro 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 declarou explicitamente parâmetros. Você pode usá-la mais de uma vez em uma função, mas todos os parâmetros inseridos são passados para todas as instâncias de @Args, conforme mostrado no exemplo a seguir.
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)
Se você transformar uma função em uma função avançada usando os atributos cmdletBinding ou Parameter, a variável automática $args não estará mais disponível na função. Funções avançadas exigem definição de parâmetro explícita.
A DSC (Configuração de Estado Desejado) do PowerShell não foi projetada para usar o fracionamento. Você não pode usar o fracionamento para passar valores para um recurso DSC. Para obter mais informações, consulte o artigo da Gael Colas Pseudo-Splatting DSC Resources.
Comentários do PowerShell
O PowerShell é um projeto código aberto. Selecione um link para fornecer comentários: