about_Splatting
簡単な説明
スプラッティングを使用して PowerShell のコマンドにパラメーターを渡す方法について説明します。
長い説明
スプラッティングは、パラメーター値のコレクションを1つの単位としてコマンドに渡す方法です。 PowerShell は、コマンドパラメーターを使用して、コレクション内の各値を関連付けます。 Splatted パラメーターの値は、標準の変数と同じように、名前付きのスプラッティング変数に格納されますが、ドル記号 $ () ではなくアットマーク ( @ ) で始まります。 At 記号は、単一の値ではなく、値のコレクションを渡すことを PowerShell に指示します。
スプラッティングを使用すると、コマンドが短く、読みやすくなります。 さまざまなコマンド呼び出しでスプラッティング値を再利用し、スプラッティングを使用して、 $PSBoundParameters 自動変数から他のスクリプトや関数にパラメーター値を渡すことができます。
Windows PowerShell 3.0 以降では、スプラッティングを使用してコマンドのすべてのパラメーターを表すこともできます。
構文
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
パラメーター名を必要としない、位置指定パラメーターのパラメーター値を指定するには、配列構文を使用します。 パラメーターの名前と値のペアを指定するには、ハッシュテーブルの構文を使用します。 Splatted の値は、パラメーターリスト内の任意の場所に配置できます。
スプラッティングの場合、すべてのパラメーターを渡すためにハッシュテーブルまたは配列を使用する必要はありません。 スプラッティングを使用していくつかのパラメーターを渡し、位置またはパラメーター名で他のパラメーターを渡すことができます。 また、複数のオブジェクトを1つのコマンドで記号して、各パラメーターに対して複数の値を渡すことはできません。
スプラッティングとハッシュテーブル
ハッシュテーブルを使用して、パラメーターの名前と値のペアを記号します。 この形式は、位置指定パラメーターやスイッチパラメーターなど、すべてのパラメーターの型に対して使用できます。 位置指定パラメーターは名前で割り当てる必要があります。
次の例では、Test.txt ファイルを同じディレクトリ内の Test2.txt ファイルにコピーする2つ Copy-Item のコマンドを比較します。
最初の例では、パラメーター名が含まれている従来の形式を使用します。
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
2番目の例では、ハッシュテーブルスプラッティングを使用します。 最初のコマンドは、パラメーター名とパラメーター値のペアのハッシュテーブルを作成し、変数に $HashArguments 格納します。 2番目のコマンドは、スプラッティングを使用してコマンド内の変数を $HashArguments 使用します。 At 記号 ( @HashArguments ) は、コマンドのドル記号 ( $HashArguments ) に代わるものです。
WhatIf スイッチパラメーターの値を指定するには、または $False を使用 $True します。
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
注意
最初のコマンドでは、アットマーク ( @ ) は splatted 値ではなくハッシュテーブルを示します。 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 が配列にラップされています。
Hello World!
例
この例では、さまざまなコマンドで splatted 値を再利用する方法を示します。 この例のコマンドは、コマンドレットを使用 Write-Host して、ホストプログラムコンソールにメッセージを書き込みます。 スプラッティングを使用して、前景色と背景色を指定します。
すべてのコマンドの色を変更するには、変数の $Colors 値を変更するだけです。
最初のコマンドは、パラメーター名と値のハッシュテーブルを作成し、そのハッシュテーブルを変数に $Colors 格納します。
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
2番目と3番目のコマンドは、コマンドで Write-Host スプラッティングの変数を使用 $Colors します。 を使用 $Colors variable するには、ドル記号 ( $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.string) です。
次の例では、変数を使用 $PSBoundParameters して、スクリプトまたは関数に渡されたパラメーター値を関数から Test2 関数に Test1 転送します。 から Test2 関数を呼び出すと、 Test1 スプラッティングが使用されます。
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
スプラッティングコマンドのパラメーター
スプラッティングを使用して、コマンドのパラメーターを表すことができます。 この手法は、プロキシ関数、つまり別のコマンドを呼び出す関数を作成するときに便利です。 この機能は 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
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)
メモ
構成 属性または****パラメーター 属性 $args を使用して関数を高度な関数にすると、自動変数は関数で使用できなくなります。 高度な関数には、明示的なパラメーター定義が必要です。
PowerShell Desired State Configuration (DSC) はスプラッティングを使用するように設計されていません。 スプラッティングを使用して、DSC リソースに値を渡すことはできません。 詳細については、「 スプラッティング DSC リソース」を参照してください。
関連項目
フィードバック
フィードバックの送信と表示