about_Splatting
簡単な説明
スプラッティングを使用して PowerShell のコマンドにパラメーターを渡す方法について説明します。
詳細な説明
Splatting は、パラメーター値のコレクションを単位としてコマンドに渡す方法です。 PowerShell は、コレクション内の各値をコマンド パラメーターに関連付けます。 Splatted パラメーター値は、標準変数のように見える名前付きスプラッティング変数に格納されますが、ドル記号 ($) ではなく At 記号 (@) で始まります。 At 記号は、1 つの値ではなく値のコレクションを渡すことを PowerShell に通知します。
スプラッティングを使用すると、コマンドが短くなり、読みやすくなります。 異なるコマンド呼び出しでスプラッティング値を再利用し、スプラッティングを使用して、 $PSBoundParameters 自動変数から他のスクリプトや関数にパラメーター値を渡すことができます。
Windows PowerShell 3.0 以降では、スプラッティングを使用してコマンドのすべてのパラメーターを表すこともできます。
構文
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
パラメーター名が不要な位置指定パラメーターにパラメーター値を指定するには、配列構文を使用します。 パラメーター名と値のペアを指定するには、ハッシュ テーブル構文を使用します。 スプラッティングされた値は、パラメーター リストの任意の場所に表示できます。
スプラッティング時に、ハッシュ テーブルまたは配列を使用してすべてのパラメーターを渡す必要はありません。 一部のパラメーターは、スプラッティングを使用して渡し、他のパラメーターを位置またはパラメーター名で渡すことができます。 また、パラメーターごとに複数の値を渡さないように、1 つのコマンドで複数のオブジェクトをスプラッタすることもできます。
PowerShell 7.1 以降では、コマンドでパラメーターを明示的に定義することで、splatted パラメーターをオーバーライドできます。
ハッシュ テーブルを使用したスプラッティング
ハッシュ テーブルを使用して、パラメーター名と値のペアをスプラトします。 この形式は、位置指定パラメーターやスイッチ パラメーターを含むすべてのパラメーター型に使用できます。 位置指定パラメーターは名前で割り当てる必要があります。
次の例では、Test.txt ファイルを同じディレクトリ内のTest2.txt ファイルにコピーする 2 つの Copy-Item コマンドを比較します。
最初の例では、パラメーター名が含まれる従来の形式を使用します。
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
2 番目の例では、ハッシュ テーブルのスプラッティングを使用します。 最初のコマンドは、パラメーター名とパラメーターと値のペアのハッシュ テーブルを作成し、 $HashArguments 変数に格納します。 2 番目のコマンドでは、スプラッティングを使用してコマンド内の $HashArguments 変数を使用します。 At 記号 (@HashArguments) は、コマンドのドル記号 ($HashArguments) を置き換えます。
WhatIf スイッチ パラメーターの値を指定するには、$Trueまたは$Falseを使用します。
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Note
最初のコマンドでは、At 記号 (@) は、スプラッティングされた値ではなくハッシュ テーブルを示します。 PowerShell のハッシュ テーブルの構文は次のとおりです。 @{<name>=<value>; <name>=<value>; ...}
配列を使用したスプラッティング
位置指定パラメーターの値をスプラッタするには、配列を使用します。パラメーター名は必要ありません。 値は配列内の位置番号の順序で指定する必要があります。
次の例では、Test.txt ファイルを同じディレクトリ内のTest2.txt ファイルにコピーする 2 つの Copy-Item コマンドを比較します。
最初の例では、パラメーター名を省略する従来の形式を使用します。 パラメーター値は、コマンドの位置順に表示されます。
Copy-Item "test.txt" "test2.txt" -WhatIf
2 番目の例では、配列スプラッティングを使用します。 最初のコマンドは、パラメーター値の配列を作成し、 $ArrayArguments 変数に格納します。 値は配列内の位置順です。 2 番目のコマンドでは、スプラッティングのコマンドで $ArrayArguments 変数を使用します。 At 記号 (@ArrayArguments) は、コマンドのドル記号 ($ArrayArguments) を置き換えます。
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
ArgumentList パラメーターの使用
いくつかのコマンドレットには、 ArgumentList パラメーターがあります。パラメーターは、コマンドレットによって実行されるスクリプト ブロックにパラメーター値を渡すために使用されます。 ArgumentList パラメーターは、スクリプト ブロックに渡される値の配列を受け取ります。 PowerShell では、配列スプラッティングを効果的に使用して、スクリプト ブロックのパラメーターに値をバインドします。 ArgumentListを使用する場合、1 つのパラメーターにバインドされた単一のオブジェクトとして配列を渡す必要がある場合は、配列を別の配列の唯一の要素としてラップする必要があります。
次の例には、文字列の配列である 1 つのパラメーターを受け取るスクリプト ブロックがあります。
$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 を配列にラップして、配列全体を 1 つのオブジェクトとしてスクリプト ブロックに渡します。
Hello World!
例
例 1: さまざまなコマンドでスプラッティングされたパラメーターを再利用する
この例では、さまざまなコマンドでスプラッティングされた値を再利用する方法を示します。 この例のコマンドでは、 Write-Host コマンドレットを使用して、ホスト プログラム コンソールにメッセージを書き込みます。 スプラッティングを使用して、前景色と背景色を指定します。
すべてのコマンドの色を変更するには、 $Colors 変数の値を変更するだけです。
最初のコマンドは、パラメーター名と値のハッシュ テーブルを作成し、 $Colors 変数にハッシュ テーブルを格納します。
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
2 番目と 3 番目のコマンドでは、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."
例 2: $PSBoundParametersを使用してパラメーターを転送する
この例では、スプラッティングと $PSBoundParameters 自動変数を使用して、パラメーターを他のコマンドに転送する方法を示します。
$PSBoundParameters自動変数は、スクリプトまたは関数の実行時に使用されるすべてのパラメーター名と値を含むディクショナリ オブジェクト (System.Collections.Generic.Dictionary) です。
次の例では、 $PSBoundParameters 変数を使用して、スクリプトまたは関数に渡されるパラメーター値 Test2 関数から Test1 関数に転送します。 両方の呼び出しから Test1 関数 Test2 スプラッティングを使用します。
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: 明示的に定義されたパラメーターを使用して splatted パラメーターをオーバーライドする
この例では、明示的に定義されたパラメーターを使用して、splatted パラメーターをオーバーライドする方法を示します。 これは、新しいハッシュテーブルを作成したり、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
}
}
例 4: 1 つのコマンドで複数のスプラッタされたオブジェクトを使用する
1 つのコマンドで複数のスプラッティングオブジェクトを使用できます。 この例では、異なるパラメーターが個別のハッシュテーブルで定義されています。 ハッシュテーブルは、1 つの Write-Host コマンドでスプラッティングされます。
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
Splatting コマンド パラメーター
スプラッティングを使用して、コマンドのパラメーターを表すことができます。 この手法は、プロキシ関数、つまり別のコマンドを呼び出す関数を作成する場合に便利です。 この機能は、Windows PowerShell 3.0 で導入されています。
コマンドのパラメーターをスプラッタするには、 @Args を使用してコマンド パラメーターを表します。 この手法は、コマンド パラメーターを列挙するよりも簡単で、呼び出されたコマンドのパラメーターが変更された場合でもリビジョンなしで動作します。
この機能では、 $Args 自動変数が使用されます。この変数には、割り当てられていないすべてのパラメーター値が含まれています。
たとえば、次の関数は Get-Process コマンドレットを呼び出します。 この関数では、 @Args は、 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
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 リソースに値を渡すことはできません。 詳細については、GaelOlas の記事 Pseudo-Splatting DSC リソースを参照してください。
関連項目
PowerShell