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 параметр, явно определив параметр в команде.
Используйте хэш-таблицу для пар параметров 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>; ...}
Используйте массив для 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 принимает массив значений, передаваемых блоку скрипта. 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!
В этом примере показано, как повторно использовать сплатированные значения в разных командах. Команды в этом примере используют 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."
В этом примере показано, как перенаправить свои параметры другим командам с помощью 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
В этом примере показано, как переопределить параметр 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
}
}
В одной команде можно использовать несколько разных объектов. В этом примере различные параметры определяются в отдельных хэш-файлах. Хэш-хэш-коды отображаются в одной 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® Windows® 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.
PowerShell кері байланысы
PowerShell — бастапқы коды ашық жоба. Пікір қалдыру үшін сілтемені таңдаңыз: