Partilhar via

sobre_Splatting

Breve descrição

Descreve como usar 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 dos parâmetros splatted são armazenados em variáveis de 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.

Splatting torna os comandos mais curtos e fáceis de ler. Você pode reutilizar os valores de splatting em diferentes chamadas de comando e usar splatting 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 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âmetros para parâmetros posicionais, nos quais os nomes de parâmetros 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 splatted pode aparecer em qualquer lugar na lista de parâmetros.

Ao utilizar splatting, não é necessário 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, é possível dispersar vários objetos num único comando, evitando passar mais de um valor para cada parâmetro.

A partir do PowerShell 7.1, é possível substituir um parâmetro splatted ao definir explicitamente um parâmetro num comando.

Splatting com tabelas de hash

Use uma tabela de hash para espalhar nomes de parâmetros e pares de valores. 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 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 dos parâmetros são incluídos.

Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf

O segundo exemplo utiliza a técnica de splatting em tabelas de hash. O primeiro comando cria uma tabela de hash de pares parameter-name e parameter-value e a armazena na variável $HashArguments. O segundo comando utiliza a variável $HashArguments num comando com splatting. O símbolo At (@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 estendido. A sintaxe para tabelas de hash no PowerShell é: @{<name>=<value>; <name>=<value>; ...}

Splatting com matrizes

Utilize uma matriz para distribuir valores como 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 dos parâmetros 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 o splatting de matriz. O primeiro comando cria uma matriz dos valores dos parâmetros e a armazena na variável $ArrayArguments. Os valores estão em ordem de posição na matriz. O segundo comando usa a variável $ArrayArguments num comando de splatting. O símbolo At (@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 a um bloco de script executado pelo cmdlet. O parâmetro ArgumentList recebe um array de valores que é passado ao bloco de script. O PowerShell está efetivamente a usar array splatting para associar os valores aos parâmetros do bloco de script. Ao usar ArgumentList, se você precisar passar uma matriz como um único objeto vinculado a um único parâmetro, deverá encapsular a matriz como o único elemento de outra matriz.

O exemplo seguinte tem um bloco de script que recebe um único parâmetro que é um array 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 está envolto num array de modo que todo o array é passado ao bloco de script como um único objeto.

Hello World!

Examples

Exemplo 1: Reutilizar parâmetros expandidos em diferentes comandos

Este exemplo mostra como reutilizar valores espalhados em comandos diferentes. Os comandos neste exemplo usam o cmdlet Write-Host para gravar mensagens no console do programa host. Usa o splatting para especificar as cores de primeiro plano e plano de fundo.

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"}

O segundo e o terceiro comandos usam a variável $Colors para splatting num comando Write-Host. Para usar o $Colors variable, substitua o cifrão ($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."

Exemplo 2: Encaminhar parâmetros usando $PSBoundParameters

Este exemplo mostra como encaminhar seus parâmetros para outros comandos usando splatting e a variável automática $PSBoundParameters.

A variável automática $PSBoundParameters é um objeto de dicionário (System.Collections.Generic.Dictionary) que contém todos os nomes de parâmetros e valores 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 a partir de Test2 utilizam 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 splat por parâmetros explicitamente definidos

Este exemplo mostra como substituir um parâmetro splatted usando parâmetros explicitamente definidos. Isso é útil quando você não deseja criar uma nova hashtable ou alterar um valor na hashtable que você está usando para splat.

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 espalhar os parâmetros, criando cada máquina virtual. No entanto, queremos que myVM2 sejam criadas em uma região diferente das outras máquinas virtuais. Em vez de ajustar o hashtable $commonParams, pode definir explicitamente o parâmetro Location em New-AzVm para substituir o valor da chave Location no $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: Usar vários objetos splatted num único comando

Você pode usar vários objetos espalhados num único comando. Neste exemplo, diferentes parâmetros são definidos em hashtables separados. As hashtables estã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

Parâmetros do comando Splatting

Você pode usar 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 espalhar os parâmetros de um comando, use @args para representar os parâmetros do comando. Esta 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 mudem.

O recurso usa a variável automática $args, que contém todos os valores de parâmetros não atribuídos.

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 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 tenha parâmetros explicitamente declarados. 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, 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&reg; Windows&reg; 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 variável automática $args não estará mais disponível na função. As funções avançadas requerem uma definição explícita de parâmetros.

A Configuração de Estado Desejado (DSC) do PowerShell não foi projetada para usar splatting. Não é possível usar splatting para passar valores para um recurso DSC. Para obter mais informações, consulte o artigo de Gael Colas Pseudo-Splatting DSC Resources.

Consulte também

  • Last updated on