about_Splatting
简短说明
介绍如何在 PowerShell 中使用散列传递将参数传递给命令。
长说明
散列传递是将参数值的集合作为一个单元传递给命令的方法。 PowerShell 将集合中的每个值与一个命令参数相关联。 散列传递的参数值存储在命名的散列传递变量中，这些变量看起来和标准变量相似，但以 At 符号 (@) 而不是美元符号 ($) 开头。 At 符号告知 PowerShell 你正在传递值集合，而不是单个值。
散列传递使命令更短，且更易于阅读。 可以在不同的命令调用中重用散列传递值，并使用散列传递将参数值从 $PSBoundParameters 自动变量传递到其他脚本和函数。
从 Windows PowerShell 3.0 开始，还可以使用散列传递来表示命令的所有参数。
语法
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
若要为不需要参数名称的位置参数提供参数值，请使用数组语法。 若要提供参数名称和值对，请使用哈希表语法。 散列传递的值可以出现在参数列表中的任何位置。
执行散列传递时，不需要使用哈希表或数组来传递所有参数。 可以使用散列传递来传递一些参数，并通过位置或参数名称传递其他参数。 此外，还可以在单个命令中散列传递多个对象，这样就不会为每个参数传递多个值。
从 PowerShell 7.1 开始，可以通过在命令中显式定义参数来覆盖散列传递的参数。
使用哈希表进行散列传递
使用哈希表可散列传递参数名称和值对。 可以将此格式用于所有参数类型，包括位置参数和开关参数。 位置参数必须按名称分配。
以下示例比较了两个 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>; ...}
使用数组进行散列传递
使用数组可散列传递位置参数的值，这不需要参数名称。 这些值必须按数组中的位置编号顺序排列。
以下示例比较了两个 Copy-Item 命令，这些命令用于将 Test.txt 文件复制到同一目录中的 Test2.txt 文件。
第一个示例使用省略参数名称的传统格式。 参数值按命令中的位置顺序显示。
Copy-Item "test.txt" "test2.txt" -WhatIf
第二个示例使用数组散列传递。 第一个命令创建参数值数组并将其存储在 $ArrayArguments 变量中。 这些值按数组中的位置顺序排列。 第二个命令在采用散列传递的命令中使用 $ArrayArguments 变量。 在该命令中，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 转发参数
此示例演示如何使用散列传递和 $PSBoundParameters 自动变量将参数转发到其他命令。
$PSBoundParameters 自动变量是一个字典对象 (System.Collections.Generic.Dictionary)，其中包含运行脚本或函数时使用的所有参数名称和值。
在以下示例中，我们使用 $PSBoundParameters 变量将传递给脚本或函数的参数值从 Test2 函数转发到 Test1 函数。 从 Test2 对 Test1 函数进行的两次调用都使用散列传递。
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：使用显式定义的参数重写散列传递的参数
此示例演示如何使用显式定义的参数重写散列传递的参数。 这在你不想生成新的哈希表或更改用于散列传递的哈希表中的值时非常有用。
$commonParams 变量存储参数，用于在 East US 位置创建虚拟机。 $allVms 变量是要创建的虚拟机的列表。 我们循环遍历该列表并使用 $commonParams 来对参数进行散列传递，以便创建每个虚拟机。 但是，我们希望 myVM2 创建在与其他虚拟机不同的区域中。 可以在 New-AzVm 中显式定义 Location 参数来取代 $commonParams 中 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 对象
可以在单个命令中使用多个 Splatted 对象。 在此示例中，不同的参数在单独的哈希表中定义。 哈希表在单个 Write-Host 命令中展开。
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
散列传递命令参数
可以使用散列传递来表示命令的参数。 此方法在创建代理函数（即调用另一个命令的函数）时非常有用。 此功能是在 Windows PowerShell 3.0 中引入的。
若要散列传递命令的参数，请使用 @Args 来表示命令参数。 这种技术比枚举命令参数更容易，无需你执行任何修改就能发挥作用，即使被调用命令的参数发生变化也是如此。
该功能使用 $Args 自动变量，其中包含所有未分配的参数值。
例如，以下函数调用 Get-Process cmdlet。 在此函数中，@Args 表示 Get-Process cmdlet 的所有参数。
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)
说明
如果使用 CmdletBinding 或 Parameter 属性将函数转换为高级函数，则 $args 自动变量将在该函数中不再可用。 高级函数需要显式参数定义。
PowerShell Desired State Configuration (DSC) 未设计为使用散列传递。 不能使用散列传递将值传入 DSC 资源。 有关详细信息，请参阅 Gael Colas 的文章伪散列传递 DSC 资源。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈