about_Splatting

簡単な説明

スプラッティングを使用して PowerShell のコマンドにパラメーターを渡す方法について説明します。

長い説明

スプラッティングは、パラメーター値のコレクションを1つの単位としてコマンドに渡す方法です。 PowerShell は、コマンドパラメーターを使用して、コレクション内の各値を関連付けます。 Splatted パラメーターの値は、標準の変数と同じように、名前付きのスプラッティング変数に格納されますが、ドル記号 () ではなくアットマーク () で始まり @ $ ます。 At 記号は、単一の値ではなく、値のコレクションを渡すことを PowerShell に指示します。

スプラッティングを使用すると、コマンドが短く、読みやすくなります。 さまざまなコマンド呼び出しでスプラッティング値を再利用し、スプラッティングを使用して、 $PSBoundParameters 自動変数から他のスクリプトや関数にパラメーター値を渡すことができます。

Windows PowerShell 3.0 以降では、スプラッティングを使用してコマンドのすべてのパラメーターを表すこともできます。

Syntax

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

パラメーター名を必要としない、位置指定パラメーターのパラメーター値を指定するには、配列構文を使用します。 パラメーターの名前と値のペアを指定するには、ハッシュテーブルの構文を使用します。 Splatted の値は、パラメーターリスト内の任意の場所に配置できます。

スプラッティングの場合、すべてのパラメーターを渡すためにハッシュテーブルまたは配列を使用する必要はありません。 スプラッティングを使用していくつかのパラメーターを渡し、位置またはパラメーター名で他のパラメーターを渡すことができます。 また、複数のオブジェクトを1つのコマンドで記号して、各パラメーターに対して複数の値を渡すことはできません。

PowerShell 7.1 では、コマンドでパラメーターを明示的に定義することによって、splatted パラメーターをオーバーライドできます。

スプラッティングとハッシュテーブル

ハッシュテーブルを使用して、パラメーターの名前と値のペアを記号します。 この形式は、位置指定パラメーターやスイッチパラメーターなど、すべてのパラメーターの型に対して使用できます。 位置指定パラメーターは、名前で割り当てる必要があります。

次の例では、同じディレクトリ内の Test.txt ファイルにTest2.txt Copy-Item 2 つのコマンドを比較します。

最初の例では、パラメーター名が含まれる従来の形式を使用します。

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

注意

最初のコマンドでは、At 記号 ( ) は、スプラット値ではなくハッシュ @ テーブルを示します。 PowerShell のハッシュ テーブルの構文は次のとおりです。 @{<name>=<value>; <name>=<value>; ...}

配列を使用したスプラッティング

配列を使用して、パラメーター名を必要としない位置指定パラメーターの値をスプラッターします。 値は、配列内の位置番号の順序である必要があります。

次の例では、同じディレクトリ内の Test.txt ファイルにTest2.txt Copy-Item 2 つのコマンドを比較します。

最初の例では、パラメーター名を省略する従来の形式を使用します。 パラメーター値は、 コマンドの位置順に表示されます。

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!

例 1: 異なるコマンドで splatted パラメーターを再利用する

この例では、さまざまなコマンドで splatted 値を再利用する方法を示します。 この例のコマンドは、コマンドレットを使用して、 Write-Host ホストプログラムコンソールにメッセージを書き込みます。 スプラッティングを使用して、前景色と背景色を指定します。

すべてのコマンドの色を変更するには、変数の値を変更するだけ $Colors です。

最初のコマンドは、パラメーター名と値のハッシュテーブルを作成し、そのハッシュテーブルを変数に格納し $Colors ます。

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

2番目と3番目のコマンドは、 $Colors コマンドでスプラッティングの変数を使用し Write-Host ます。 を使用するには $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."

例 2: $PSBoundParameters を使用してパラメーターを転送する

この例では、スプラッティングと自動変数を使用して、他のコマンドにパラメーターを転送する方法を示し $PSBoundParameters ます。

$PSBoundParameters自動変数は、スクリプトまたは関数の実行時に使用されるすべてのパラメーター名と値を含むディクショナリオブジェクト (system.string) です。

次の例では、 変数を使用して、スクリプトまたは関数に渡されたパラメーター値を $PSBoundParameters Test2 関数から 関数に転送 Test1 します。 どちらの呼び出しでも Test1 、スプラッティング Test2 が使用されます。

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

例 3: 明示的に定義されたパラメーターでスプラット パラメーターをオーバーライドする

この例では、明示的に定義されたパラメーターを使用してスプラット パラメーターをオーバーライドする方法を示します。 これは、新しいハッシュテーブルを構築したり、スプラッターに使用しているハッシュテーブルの値を変更したりしたくない場合に便利です。

変数 $commonParams には、場所に仮想マシンを作成するパラメーターが格納 East US されます。 変数 $allVms は、作成する仮想マシンの一覧です。 リストをループ処理し、 を使用 $commonParams して各仮想マシンを作成するパラメーターをスプラッターします。 ただし、他 myVM2 の仮想マシンとは異なるリージョンに作成する必要があります。 ハッシュテーブルを調整する代わりに、 で Location パラメーターを明示的に定義して、 内のキーの値より代わりに $commonParams New-AzVm Location 使用できます $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
    }
}

スプラッティング コマンド パラメーター

スプラッティングを使用して、コマンドのパラメーターを表します。 この手法は、プロキシ関数 (つまり、別のコマンドを呼び出す関数) を作成する場合に便利です。 この機能は、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)

メモ

CmdletBinding 属性または Parameter 属性のいずれかを使用して関数を高度な関数にした場合、自動変数は関数 $args で使用できなくなりました。 高度な関数には、明示的なパラメーター定義が必要です。

PowerShell Desired State Configuration (DSC) はスプラッティングを使用するように設計されていない。 スプラッティングを使用して DSC リソースに値を渡すすることはできません。 詳細については、Gael Colas の記事「 擬似スプラッティング DSC リソース」を参照してください

こちらもご覧ください

about_Arrays

about_Automatic_Variables

about_Hash_Tables

about_Parameters