關於 Splatting

發行項
05/09/2024

簡短描述

描述如何使用 Splatting 將參數傳遞至 PowerShell 中的命令。

詳細描述

[本主題是由 2012 年腳本遊戲進階層之系統管理員 Mississippi 的 Rohn Edwards 所參與。 Windows PowerShell 3.0 版修訂。

Splatting 是將參數值集合傳遞至命令做為單位的方法。 PowerShell 會將集合中的每個值與命令參數產生關聯。 Splatted 參數值會儲存在具名的splatting變數中，看起來像標準變數，但開頭是 At 符號 () @ ，而不是貨幣符號 () $ 。 At 符號會告知 PowerShell 您正在傳遞值的集合，而不是單一值。

Splatting 可讓您的命令更短且更容易閱讀。您可以在不同的命令呼叫中重複使用splatting值，並使用splatting將參數值從 $PSBoundParameters 自動變數傳遞至其他腳本和函式。

從 Windows PowerShell 3.0 開始，您也可以使用 splatting 來代表命令的所有參數。

SYNTAX

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

若要提供位置參數的參數值，其中不需要參數名稱，請使用數位語法。若要提供參數名稱和值組，請使用哈希表語法。 splatted 值可以出現在參數清單中的任何位置。

展開時，您不需要使用哈希表或數位來傳遞所有參數。您可以使用splatting傳遞某些參數，並依位置或參數名稱傳遞其他參數。此外，您也可以在單一命令中 Splat 多個物件，以便針對每個參數傳遞不超過一個值。

使用哈希表進行 SPLATTING

使用哈希表來 Splat 參數名稱和值組。您可以針對所有參數類型使用此格式，包括位置參數和參數。位置參數必須依名稱指派。

下列範例會比較將 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 符號 (@) 表示哈希表，而不是 splatted 值。 PowerShell 中哈希表的語法如下： @{\<name\>=\<value\>; \<name\>=\<value\>; ...}*

SPLATTING WITH ARRAYS

針對不需要參數名稱的位置參數，請使用數位來Splat值。這些值必須以位置數字順序排列在陣列中。

下列範例會比較將 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

範例

此範例示範如何在不同的命令中重複使用splatted值。此範例中的命令會 Write-Host 使用 Cmdlet 將訊息寫入主機程式控制台。它會使用 Splatting 來指定前景和背景色彩。

若要變更所有命令的色彩，只要變更變數的值 $Colors 即可。

第一個命令會建立參數名稱和值的哈希表，並將哈希表儲存在變數中 $Colors 。

$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}

第二和第三個Write-Host命令會$Colors使用變數在命令中展開。若要使用 $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 automatic變數，將其參數轉送至其他命令。

自動 $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

SPLATTING 命令參數

您可以使用splatting來代表命令的參數。當您建立 Proxy 函式時，這項技術很有用，也就是呼叫另一個命令的函式。此功能是在 Windows PowerShell 3.0 中引進。

若要 Splat 命令的參數，請使用 @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)