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

about_Splatting

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

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

Длинное описание

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

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

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

Синтаксис

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

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

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

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

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

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

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

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

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

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

Чтобы указать значение параметра коммутатора WhatIf, используйте $true или $false.

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

Заметка

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

Splatting с массивами

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

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

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

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

Вы можете использовать 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 (DSC) не была разработана для использования сплатирования. Нельзя использовать splatting для передачи значений в ресурс DSC. Дополнительные сведения см. в статье Gael Colas Pseudo-Splatting DSC Resources.

См. также

  • Last updated on