Поделиться через


about_Splatting

Краткое описание

Описывает, как использовать сплаттинг для передачи параметров в команды в PowerShell.

Подробное описание

Splatting — это метод передачи коллекции значений параметров команде в виде единицы. PowerShell связывает каждое значение в коллекции с параметром команды. Значения параметров splatted хранятся в именованных переменных splatting, которые выглядят как стандартные переменные, но начинаются с символа At () вместо@ знака доллара ($). Символ At сообщает PowerShell, что вы передаете коллекцию значений, а не одно значение.

Сплаттинг делает команды более короткими и удобными для чтения. Значения сплаттинга можно повторно использовать в разных вызовах команд и использовать сплаттинг для передачи значений параметров из автоматической $PSBoundParameters переменной в другие скрипты и функции.

Начиная с Windows PowerShell 3.0, можно также использовать сплаттинг для представления всех параметров команды.

Синтаксис

<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>

Чтобы предоставить значения параметров для позиционных параметров, в которых имена параметров не требуются, используйте синтаксис массива. Чтобы указать пары имени параметра и значения, используйте синтаксис хэш-таблицы. Значение splatted может отображаться в любом месте списка параметров.

При сплаттинге не нужно использовать хэш-таблицу или массив для передачи всех параметров. Некоторые параметры можно передать с помощью сплаттинга, а другие — по позиции или по имени параметра. Кроме того, вы можете выполнить несколько объектов в одной команде, чтобы не передавать более одного значения для каждого параметра.

В PowerShell 7.1 можно переопределить параметр splatted, явно определив параметр в команде.

Сплаттинг с хэш-таблицами

Используйте хэш-таблицу для создания пар имен параметров splat и значений. Этот формат можно использовать для всех типов параметров, включая позиционные параметры и параметры switch. Позиционные параметры должны назначаться по имени.

В следующих примерах сравниваются две Copy-Item команды, которые копируют файл Test.txt в файл Test2.txt в том же каталоге.

В первом примере используется традиционный формат, в котором включаются имена параметров.

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

Во втором примере используется сплаттинг хэш-таблицы. Первая команда создает хэш-таблицу пар "имя параметра" и "параметр-значение" и сохраняет ее в переменной $HashArguments . Вторая команда использует $HashArguments переменную в команде со сплаттингом. Символ At (@HashArguments) заменяет знак доллара ($HashArguments) в команде.

Чтобы указать значение для параметра whatIf switch, используйте $True или $False.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
  WhatIf = $true
}
Copy-Item @HashArguments

Примечание

В первой команде символ At (@) обозначает хэш-таблицу, а не сплаттовое значение. Синтаксис хэш-таблиц в PowerShell: @{<name>=<value>; <name>=<value>; ...}

Сплаттинг с массивами

Используйте массив для splat-значений для позиционных параметров, которые не требуют имен параметров. Значения должны быть в массиве в порядке номеров позиций.

В следующих примерах сравниваются две Copy-Item команды, которые копируют файл Test.txt в файл Test2.txt в том же каталоге.

В первом примере используется традиционный формат, в котором имена параметров опущены. Значения параметров отображаются в команде в порядке позиции.

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

Во втором примере используется сплаттинг массива. Первая команда создает массив значений параметров и сохраняет его в переменной $ArrayArguments . Значения в массиве находятся в порядке расположения. Вторая команда использует $ArrayArguments переменную в команде в сплаттинге. Символ At (@ArrayArguments) заменяет знак доллара ($ArrayArguments) в команде.

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf

Использование параметра ArgumentList

Несколько командлетов имеют параметр ArgumentList , который используется для передачи значений параметров блоку скрипта, который выполняется командлетом. Параметр ArgumentList принимает массив значений, передаваемых в блок скрипта. PowerShell эффективно использует сплаттинг массива для привязки значений к параметрам блока скрипта. Если при использовании ArgumentList необходимо передать массив в виде одного объекта, привязанного к одному параметру, необходимо заключив массив в качестве единственного элемента другого массива.

В следующем примере есть блок скрипта, который принимает один параметр, представляющий собой массив строк.

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
  } -ArgumentList $array

В этом примере в блок скрипта передается только первый элемент в $array .

Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)

В этом примере упаковывается в массив, $array чтобы весь массив передавался в блок скрипта в виде одного объекта.

Hello World!

Примеры

Пример 1. Повторное использование параметров splatted в разных командах

В этом примере показано, как повторно использовать сплатированные значения в разных командах. Команды в этом примере используют командлет для Write-Host записи сообщений в консоль ведущего приложения. Он использует сплаттинг для указания цветов переднего плана и фона.

Чтобы изменить цвета всех команд, просто измените значение переменной $Colors .

Первая команда создает хэш-таблицу имен и значений параметров и сохраняет хэш-таблицу в переменной $Colors .

$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}

Вторая и третья команды используют $Colors переменную для сплаттинга в команде Write-Host . Чтобы использовать , замените $Colors variableзнак доллара ($Colors) символом 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."

Пример 2. Пересылка параметров с помощью $PSBoundParameters

В этом примере показано, как пересылать их параметры в другие команды с помощью splatting и автоматической переменной $PSBoundParameters .

Автоматическая $PSBoundParameters переменная — это объект словаря (System.Collections.Generic.Dictionary), содержащий все имена и значения параметров, используемые при выполнении скрипта или функции.

В следующем примере переменная используется $PSBoundParameters для пересылки значений параметров, переданных в скрипт или функцию из Test2 функции в функцию Test1 . Оба вызова Test1 функции из Test2 используют 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

Пример 3. Переопределение сплатированных параметров явно определенными параметрами

В этом примере показано, как переопределить параметр splatted с помощью явно определенных параметров. Это полезно, если вы не хотите создавать новую хэш-систему или изменять значение в хэш-сводке, используемой для splat.

Переменная $commonParams сохраняет параметры для создания виртуальных машин в расположении East US . Переменная $allVms представляет собой список создаваемых виртуальных машин. Мы циклически просматриваем список и используем $commonParams для splat параметры для создания каждой виртуальной машины. Тем не менее, мы хотим myVM2 создать в регионе, отличном от других виртуальных машин. Вместо настройки $commonParams хэш-сводки можно явно определить параметр Location в New-AzVm , чтобы заменять значение Location ключа в $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
    }
}

Пример 4. Использование нескольких объектов splatted в одной команде

В одной команде можно использовать несколько сплаттированных объектов. В этом примере различные параметры определяются в отдельных хэш-сводках. Хэш-сводки сброшены в одной Write-Host команде.

$a = @{
    Message         = 'Hello', 'World!'
}
$b = @{
    Separator       = '|'
}
$c = @{
    BackgroundColor = 'Cyan'
    ForegroundColor = 'Black'
}
Write-Host @a @b @c

Параметры команды Splatting

Для представления параметров команды можно использовать сплаттинг. Этот метод полезен при создании прокси-функции, то есть функции, которая вызывает другую команду. Эта функция появилась в Windows PowerShell 3.0.

Чтобы определить параметры команды, используйте для @Args представления параметров команды. Этот метод проще, чем перечисление параметров команды, и работает без изменения, даже если параметры вызываемой команды изменяются.

Функция использует автоматическую $Args переменную, которая содержит все значения неназначенных параметров.

Например, следующая функция вызывает Get-Process командлет . В этой функции @Args представляет все параметры командлета Get-Process .

function Get-MyProcess { Get-Process @Args }

При использовании Get-MyProcess функции все неназначенные параметры и значения параметров передаются @Argsв , как показано в следующих командах.

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\...

Можно использовать @Args в функции, которая имеет явно объявленные параметры. Его можно использовать несколько раз в функции, но все вводимые параметры передаются всем экземплярам @Args, как показано в следующем примере.

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)

Примечания

При превратив функцию в расширенную функцию с помощью атрибутов CmdletBinding или Parameter , $args автоматическая переменная больше не будет доступна в функции. Для расширенных функций требуется явное определение параметра.

PowerShell Desired State Configuration (DSC) не предназначен для использования сплаттинга. Нельзя использовать сплаттинг для передачи значений в ресурс DSC. Дополнительные сведения см. в статье Gael Colas о псевдосплаттинге ресурсов DSC.

См. также раздел