关于泼溅

简短描述

描述如何使用展开将参数传递给 PowerShell 中的命令。

详细描述

展开是将参数值集合作为一个单元传递给命令的方法。 PowerShell 将集合中的每个值与命令参数相关联。展开参数值存储在命名的展开变量中，这些变量看起来像标准变量，但以 At 符号 (@) 开头，而不是美元符号 ($)。 At 符号告诉 PowerShell 您正在传递值的集合，而不是单个值。

泼溅使您的命令更短且更易于阅读。您可以在不同的命令调用中重复使用展开值，并使用展开将参数值从 $PSBoundParameters 自动变量传递到其他脚本和函数。

从 Windows PowerShell 3.0 开始，您还可以使用展开来表示命令的所有参数。

句法

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

要为不需要参数名称的位置参数提供参数值，请使用数组语法。要提供参数名称和值对，请使用哈希表语法。 splatted 值可以出现在参数列表中的任何位置。

splatting时，不需要使用哈希表或数组来传递所有参数。您可以使用展开来传递一些参数，并通过位置或参数名称传递其他参数。此外，您可以在单个命令中展开多个对象，这样您就不会为每个参数传递多个值。

从 PowerShell 7.1 开始，您可以通过在命令中显式定义参数来覆盖展开参数。

使用哈希表进行泼溅

使用哈希表来展开参数名称和值对。您可以将此格式用于所有参数类型，包括位置参数和开关参数。位置参数必须按名称分配。

以下示例比较将 Test.txt 文件复制到同一目录中的 Test2.txt 文件的两个 Copy-Item 命令。

第一个示例使用包含参数名称的传统格式。

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 中哈希表的语法为：@{=; =； ...}

用数组进行泼溅

使用数组来表示位置参数的值，不需要参数名称。这些值必须按数组中的位置编号顺序排列。

以下示例比较将 Test.txt 文件复制到同一目录中的 Test2.txt 文件的两个 Copy-Item 命令。

第一个示例使用省略参数名称的传统格式。参数值按命令中的位置顺序出现。

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

第二个示例使用数组展开。第一个命令创建一个参数值数组并将其存储在 $ArrayArguments 变量中。这些值按数组中的位置顺序排列。第二个命令在splatting命令中使用$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 变量，请将美元符号 ($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 函数。从 Test2 对 Test1 函数的两次调用都使用了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 变量存储在美国东部 位置创建虚拟机的参数。 $allVms 变量是要创建的虚拟机的列表。我们循环遍历列表并使用 $commonParams 来显示参数以创建每个虚拟机。但是，我们希望在与其他虚拟机不同的区域中创建 myVM2。您可以在 New-AzVm 中显式定义 Location 参数来取代 Location 的值，而不是调整 $commonParams 哈希表 输入$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：在单个命令中使用多个展开对象

您可以在单个命令中使用多个展开的对象。在此示例中，不同的参数在单独的哈希表中定义。哈希表在单个 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 的文章 Pseudo-Splatting DSC 资源。

参见

• about_Arrays
• about_Automatic_Variables
• about_Hash_Tables
• about_参数