Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0
РАЗДЕЛ
about_Splatting
КРАТКОЕ ОПИСАНИЕ
Содержит описание использования сплаттинга для передачи параметров в команды Windows PowerShell®.
ПОДРОБНОЕ ОПИСАНИЕ
[Этот раздел был предоставлен Роном Эдвардом (Rohn Edwards) из города Галфпорт, штат Миссисипи, являющимся системным администратором и победителем конкурса Scripting Games 2012 в категории Advanced. Пересмотрено для версии Windows PowerShell 3.0.]
Сплаттинг — это способ передачи коллекции значений параметров в команду в виде единого целого. Windows PowerShell связывает каждое значение в коллекции с параметром команды. Значения параметров, переданные путем сплаттинга, хранятся в именованных переменных сплаттинга, которые похожи на обычные переменные, но начинаются с символа @, а не со знака доллара ($). Символ @ сообщает среде Windows PowerShell о том, что вы передаете коллекцию значений, а не одно значение.
Благодаря сплаттингу команды получаются короче и удобнее для чтения. Вы можете повторно использовать значения сплаттинга в других вызовах команд и применять сплаттинг для передачи значений параметров из автоматической переменной $PSBoundParameters в другие сценарии и функции.
Начиная с версии Windows PowerShell 3.0 можно использовать сплаттинг для представления всех параметров команды.
СИНТАКСИС
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Для предоставления значений позиционных параметров, не требующих имен, используйте синтаксис массива. Для предоставления пар, состоящих из имени и значения параметра, используйте синтаксис хэш-таблицы. Передаваемое путем сплаттинга значение может находиться в любом месте списка параметров.
При использовании сплаттинга не требуется передавать все параметры в хэш-таблице или массиве. Вы можете передать некоторые параметры с помощью сплаттинга, а другие — по позиции или имени параметра. Кроме того, вы можете передать путем сплаттинга несколько объектов в одной команде, чтобы для каждого параметра было передано не более одного значения.
СПЛАТТИНГ С ИСПОЛЬЗОВАНИЕМ ХЭШ-ТАБЛИЦ
Используйте хэш-таблицу для сплаттинга пар, состоящих из имени и значения параметра. Этот формат можно использовать для параметров любых типов, включая позиционные и именованные параметры, а также параметры-переключатели.
В примерах ниже сравниваются две команды Copy-Item, которые копируют файл Test.txt в файл Test2.txt в том же каталоге.
В первом примере используется традиционный формат с именами параметров.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
Во втором примере используется сплаттинг хэш-таблицы. Первая команда создает хэш-таблицу из пар «имя параметра — значение параметра» и сохраняет ее в переменной $HashArguments. Во второй команде используется переменная $HashArguments со сплаттингом. Символ @ (@HashArguments) заменяет в команде знак доллара ($HashArguments).
Чтобы указать значение параметра-переключателя WhatIf, используйте $True или $False.
PS C:\>$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
PS C:\>Copy-Item @HashArguments
Примечание. В первой команде символ @ указывает на хэш-таблицу, а не на передаваемое путем сплаттинга значение. Синтаксис хэш-таблиц в Windows PowerShell выглядит так: @{ <имя>=<значение>; <имя>=<значение>; …}
СПЛАТТИНГ С ИСПОЛЬЗОВАНИЕМ МАССИВОВ
Используйте массив для сплаттинга значений позиционных параметров, которые не требуют имен. Значения должны быть упорядочены в массиве по номеру позиции.
В примерах ниже сравниваются две команды Copy-Item, которые копируют файл Test.txt в файл Test2.txt в том же каталоге.
В первом примере используется традиционный формат без имен параметров. Значения параметров указаны в команде в порядке их позиций.
Copy-Item "test.txt" "test2.txt" -WhatIf
Во втором примере используется сплаттинг массива. Первая команда создает массив значений параметров и сохраняет его в переменной $ArrayArguments. Значения в массиве упорядочены по номеру позиции. Во второй команде используется переменная $ArrayArguments со сплаттингом. Символ @ (@ArrayArguments) заменяет в команде знак доллара ($ArrayArguments).
PS C:\>$ArrayArguments = "test.txt", "test2.txt"
PS C:\>Copy-Item @ArrayArguments -WhatIf
ПРИМЕРЫ
В этом примере показано, как повторно использовать передаваемые путем сплаттинга значения в разных командах. В командах этого примера используется командлет Write-Host для записи сообщений в консоль ведущей программы. С помощью сплаттинга задаются цвета переднего плана и фона.
Чтобы изменить цвета всех команд, просто измените значение переменной $Colors.
Первая команда создает хэш-таблицу с именами и значениями параметров и сохраняет ее в переменной $Colors.
$Colors = @{ForegroundColor = "black"
BackgroundColor = "white"}
Вторая и третья команды используют переменную $Colors для сплаттинга в команде Write-Host. Для использования переменной $Colors замените знак доллара ($Colors) на символ @ (@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."
В этом примере показано, как передавать параметры в другие команды с помощью сплаттинга и автоматической переменной $PSBoundParameters.
Автоматическая переменная $PSBoundParameters является словарем (System.Collections.Generic.Dictionary), который содержит имена и значения всех параметров, используемых при выполнении сценария или функции.
В примере ниже переменная $PSBoundParameters используется для пересылки значений параметров, передаваемых в сценарий, или функцию, передаваемую из функции Test2 в функцию Test1. Оба вызова функции Test1 из функции Test2 задействуют сплаттинг.
function Test1
{
param($a, $b, $c)
$a
$b
$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
$LimitedParameters = $PSBoundParameters
$LimitedParameters.Remove("a") | Out-Null
Test1 @LimitedParameters
}
PS C:\> Test2 -a 1 -b 2 -c 3
1
2
3
2
3
СПЛАТТИНГ ПАРАМЕТРОВ КОМАНДЫ
Сплаттинг можно использовать для представления параметров команды. Этот прием полезен при создании прокси-функции, то есть функции, которая вызывает другую команду. Эта возможность появилась в версии Windows PowerShell 3.0.
Чтобы выполнить сплаттинг параметров команды, используйте переменную @Args для их представления. Этот прием проще в использовании, чем перечисление параметров команды, и не требует внесения исправлений даже при изменении параметров вызываемой команды.
Эта функция использует автоматическую переменную $Args, которая содержит значения всех параметров, которые не были заданы. Вставьте здесь текст раздела.
Например, приведенная ниже функция вызывает командлет Get-Process. В этой функции переменная @Args представляет все параметры командлета Get-Process.
function Get-MyProcess { Get-Process @Args }
При использовании функции Get-MyProcess все незаданные параметры и их значения передаются в переменную @Args, как показано в примере ниже.
PS C:\> 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
PS C:\> Get-MyProcess -Name PowerShell_Ise -FileVersionInfo
ProductVersion FileVersion FileName
-------------- ----------- --------
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe
Переменную @Args можно использовать в функции, которая имеет явно объявленные параметры. Ее можно использовать в функции несколько раз, но все введенные параметры передаются во все экземпляры @Args, как показано в примере ниже.
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
PS C:\> Get-MyCommand -P -C -Name PowerShell
Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
408 28 75568 83176 620 1.33 1692 powershell
Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
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
СМ. ТАКЖЕ
about_Arrays
about_Automatic_Variables
about_Hash_Tables
about_Parameters