about_Splatting
简短说明
介绍如何使用展开将参数传递给 PowerShell 中的命令。
长说明
Splatting 是一种将参数值集合作为一个单元传递给命令的方法。 PowerShell 将集合中的每个值与命令参数相关联。 展开的参数值存储在命名的 splatting 变量中,这些变量看起来像标准变量,但以 At 符号开头, @
() 而不是美元符号 ($
) 。 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 开始,可以通过在命令中显式定义参数来替代已展开的参数。
使用哈希表进行展开
使用哈希表来展开参数名称和值对。 可以将此格式用于所有参数类型,包括位置参数和开关参数。 位置参数必须按名称分配。
以下示例比较了将 Test.txt 文件复制到同一目录中的 Test2.txt 文件的两 Copy-Item
个命令。
第一个示例使用包含参数名称的传统格式。
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
第二个示例使用哈希表展开。 第一个命令创建参数名称对和参数值对的哈希表,并将其存储在 变量中 $HashArguments
。 第二个命令在 $HashArguments
具有 splatting 的命令中使用 变量。 At 符号 (@HashArguments
) 替换命令中的美元符号 ($HashArguments
) 。
若要为 WhatIf 开关参数提供值,请使用 $True
或 $False
。
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
注意
在第一个命令中,At 符号 (@
) 指示哈希表,而不是展开的值。 PowerShell 中哈希表的语法为: @{<name>=<value>; <name>=<value>; ...}
使用数组进行展开
使用数组为不需要参数名称的位置参数扩展值。 值必须按数组中的位置编号顺序排列。
以下示例比较了将 Test.txt 文件复制到同一目录中的 Test2.txt 文件的两 Copy-Item
个命令。
第一个示例使用省略参数名称的传统格式。 参数值在命令中按位置顺序显示。
Copy-Item "test.txt" "test2.txt" -WhatIf
第二个示例使用数组展开。 第一个命令创建参数值的数组,并将其存储在 变量中 $ArrayArguments
。 这些值在数组中按位置顺序排列。 第二个命令在 $ArrayArguments
splatting 命令中使用 变量。 At 符号 (@ArrayArguments
) 替换命令中的美元符号 ($ArrayArguments
) 。
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
使用 ArgumentList 参数
多个 cmdlet 具有 ArgumentList 参数,用于将参数值传递给 cmdlet 执行的脚本块。 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:在不同的命令中重复使用已展开的参数
此示例演示如何在不同的命令中重复使用已展开的值。 此示例中的命令使用 Write-Host
cmdlet 将消息写入主机程序控制台。 它使用展开来指定前景色和背景色。
若要更改所有命令的颜色,只需更改 变量的值 $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
$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
}
Test2 -a 1 -b 2 -c 3
1
2
3
2
3
示例 3:使用显式定义的参数替代已展开的参数
此示例演示如何使用显式定义的参数替代已展开的参数。 当你不想生成新的哈希表或更改用于 splat 的哈希表中的值时,这非常有用。
变量 $commonParams
存储用于在 East US
位置创建虚拟机的参数。 变量 $allVms
是要创建的虚拟机的列表。 我们将循环访问该列表,并使用 $commonParams
来展开参数来创建每个虚拟机。 但是,我们希望 myVM2
在与其他虚拟机不同的区域中创建。 可以显式在 $commonParams
中New-AzVm
定义 Location 参数以取代 中$commonParams
键的值Location
,而不是调整哈希表。
$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
}
}
Splatting 命令参数
可以使用 splatting 来表示命令的参数。 创建代理函数(即调用另一个命令的函数)时,此方法非常有用。 此功能在 Windows PowerShell 3.0 中引入。
若要展开命令的参数,请使用 @Args
表示命令参数。 此方法比枚举命令参数更容易,即使调用的命令的参数发生更改,此方法也无需修订。
该功能使用 $Args
自动变量,其中包含所有未分配的参数值。
例如,以下函数调用 Get-Process
cmdlet。 在此函数中, @Args
表示 cmdlet 的所有参数 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
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.e
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
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.14393.0 (rs1_release.160715-1616
FileDescription: Windows PowerShell
Product: Microsoft Windows Operating System
ProductVersion: 10.0.14393.0
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 资源。