about_Splatting

  • Статья

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

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

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

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

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

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

Синтаксис

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

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

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

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

Splatting с хэш-таблицами

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

В следующих примерах сравниваются две 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>; ...}

Splatting с массивами

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

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

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

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

Во втором примере используется splatting массива. Первая команда создает массив значений параметров и сохраняет его в переменной $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 командлет для записи сообщений в консоль программы узла. Для указания цветов переднего плана и фона используется splatting.

Чтобы изменить цвета всех команд, просто измените значение переменной $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 использования сплатирования.

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 для создания каждой виртуальной машины параметры. Однако мы хотим 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. Использование нескольких разных объектов в одной команде

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

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

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

Вы можете использовать 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)

Примечания.

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

Конфигурация требуемого состояния PowerShell (DSC) не была разработана для использования сплатирования. Нельзя использовать splatting для передачи значений в ресурс DSC. Дополнительные сведения см. в статье Gael Colas Псевдо-Splatting DSC Resources.

См. также