about_Splatting
適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
トピック
about_Splatting
簡単な説明
Windows PowerShell® でスプラッティングを使用して、コマンドにパラメーターを渡す方法について説明します。
詳細な説明
[このトピックはミシシッピ州 Gulfport の Rohn Edwards の寄稿です。彼はシステム アドミニストレーターであり、2012 Scripting Games の Advanced Division で優勝しました。Windows PowerShell 3.0 に合わせて改訂されています。]
スプラッティングは、パラメーター値のコレクションをまとめてコマンドに渡す手法です。Windows PowerShell はコレクションのそれぞれの値をコマンドのパラメーターに関連付けます。スプラットされたパラメーター値は、名前付きスプラッティング変数に格納されます。名前つきスプラッティング変数は普通の変数のように見えますが、ドル記号 ($) の代わりにアットマーク (@) で始まります。アットマークは Windows PowerShell に対して、引数が単一の値ではなくコレクションとして渡されることを伝えます。
スプラッティングはコマンドを短くし、読みやすくします。スプラッティング値は別のコマンドの呼び出しで再利用できます。また、スプラッティングを利用して、パラメーター値を $PSBoundParameters 自動変数から他のスクリプトや関数に渡すことができます。
Windows PowerShell 3.0 以降では、コマンドの全パラメーターをスプラッティングで表すことができます。
構文
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
パラメーター名が不要な位置指定パラメーターの値を指定するには、配列の構文を使用します。パラメーター名と値のペアを指定するには、ハッシュ テーブル構文を使用します。スプラットされた値は、パラメーター リストのどこにでも配置できます。
スプラッティングの際に、ハッシュ テーブルまたは配列ですべてのパラメータを渡さなくても構いません。いくつかのパラメーターをスプラッティングで渡し、他のパラメーターを位置やパラメーター名で渡すことができます。また、1 つのコマンド内にで複数のオブジェクトをスプラットできるので、各パラメーターに2つ以上値渡す必要がなくなります。
ハッシュ テーブルによるスプラッティング
パラメーター名と値のペアをスプラットするにはハッシュ テーブルを使います。この形式は、位置指定パラメーター、名前付きパラメータおよびスイッチ パラメーターを含む、すべての種類のパラメーターに対して使うことができます。
次の例では、同一ディレクトリ内で Test.txt ファイルを Test2.txt ファイルにコピーする 2 つの Copy-Item コマンドを比較します。
最初の例では、パラメーター名が含まれる従来の形式を使用します。
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
2 番目の例では、ハッシュ テーブルによるスプラッティングを使用します。最初のコマンドは、パラメーターの名前と値のペアのハッシュ テーブルを作成し、それを $HashArguments 変数に格納します。2 番目のコマンドでは、スプラッティング用いたコマンド中で $HashArguments 変数を使用します。コマンド中のドル記号 ($HashArguments) はアットマーク (@HashArguments) で置き換えられます。
WhatIf スイッチ パラメーターの値を指定するには、$True または $False を使用します。
PS C:\>$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true }
PS C:\>Copy-Item @HashArguments
注記: 最初のコマンド中のアットマーク (@) はスプラットされた値ではなく、ハッシュ テーブルを示します。Windows PowerShell におけるハッシュ テーブルの構文は次の通りです:@{ <name>=<value>; <name>=<value>; …}
配列によるスプラッティング
パラメーター名を必要としない位置指定パラメーターの値をスプラットするには、配列を使用します。値は、配列内の位置番号順に記述する必要があります。
次の例では、同一ディレクトリ内で Test.txt ファイルを Test2.txt ファイルにコピーする 2 つの Copy-Item コマンドを比較します。
最初の例では、パラメーター名を省略する従来の形式を使用しています。パラメーターの値は、コマンド内の位置順で記述します。
Copy-Item "test.txt" "test2.txt" -WhatIf
2 番目の例では、配列によるスプラッティングを使用しています。最初のコマンドでは、パラメーター値の配列を作成し、$ArrayArguments 変数に格納します。値は、配列内の位置順で並びます。2 番目のコマンドでは、スプラッティングを行うコマンド中で $ArrayArguments 変数を使用します。コマンド中のドル記号 ($ArrayArguments) はアットマーク (@ArrayArguments) で置き換えられます。
PS C:\>$ArrayArguments = "test.txt", "test2.txt"
PS C:\>Copy-Item @ArrayArguments -WhatIf
例
この例では、スプラットされた値を別のコマンドで再利用する方法を示します。この例のコマンドでは、Write-host コマンドレットを使用して、ホスト プログラムのコンソールにメッセージを書き込みます。前景色と背景色を指定するのにスプラッティングを使用しています。
$Colors 変数の値を変更するだけで、すべてのコマンドの色を変更できます。
最初のコマンドは、パラメーターの名前と値のペアのハッシュ テーブルを作成し、それを $Colors 変数に格納します。
$Colors = @{ForegroundColor = "black"
BackgroundColor = "white"}
2 番目と 3 番目のコマンドは、Write-host コマンドで $Colors 変数を使用してスプラッティングを行います。$Colors 変数を使用するには、アットマーク (@Colors) でドル記号 ($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."
この例では、スプラッティングおよび $PSBoundParameters 自動変数を使用して、それらのパラメーターを他のコマンドに転送する方法を示します。
$PSBoundParameters 自動変数は、スクリプトまたは関数の実行時に使用されるすべてのパラメーター名と値を格納するディクショナリ (System.Collections.Generic.Dictionary) です。
次の例では、$PSBoundParameters 変数を使用して、スクリプトまたは関数に渡されたパラメーター値を、Test2 関数から Test1 関数に渡します。Test2 から Test1 関数への 2 つの呼び出しでは、どちらもスプラッティングを使用します。
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
}
PS C:\> Test2 -a 1 -b 2 -c 3
1
2
3
2
3
コマンド パラメーターのスプラッティング
スプラッティングでコマンドのパラメーターを表すことができます。この技法は、プロキシ関数、つまり他のコマンドを呼び出す関数を作成する場合に便利です。この機能は Windows PowerShell 3.0 で導入されました。
コマンドのパラメーターをスプラットするには、コマンドのパラメーター群を @Args で表します。この技法は、コマンドのパラメーターを列挙するよりも簡単で、呼び出されるコマンドのパラメーターが変更された場合でも変更不要で機能します。
この機能では、値の代入されていないパラメーターの値をすべて含む $Args 自動変数を使用します。ここにセクションの本文を挿入します。
次の例では、関数から Get-Process コマンドレットを呼び出します。この関数では、@Args は、Get-Process コマンドレットの全てのパラメーターを表します。
function Get-MyProcess { Get-Process @Args }
Get MyProcess 関数を使用する際には、次の例のように、値の代入されていない全てのパラメーターおよびパラメーター値が @Args に渡されます。
PS C:\> 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
PS C:\> Get-MyProcess -Name PowerShell_Ise -FileVersionInfo
ProductVersion FileVersion FileName
-------------- ----------- --------
6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe
@Args はパラメーターを明示的に宣言した関数で使用できます。@Args は 1 つの関数で複数回使用できますが、入力するすべてのパラメーターは、次の例で示すように、@Args のすべてのインスタンスに渡されます。
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
PS C:\> 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.exe
Extension : .exe
Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
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
関連項目
about_Arrays
about_Automatic_Variables
about_Hash_Tables
about_Parameters