スプラッティングについてAbout Splatting

簡単な説明Short description

スプラッティングを使用して PowerShell のコマンドにパラメーターを渡す方法について説明します。Describes how to use splatting to pass parameters to commands in PowerShell.

長い説明Long description

スプラッティングは、パラメーター値のコレクションを1つの単位としてコマンドに渡す方法です。Splatting is a method of passing a collection of parameter values to a command as a unit. PowerShell は、コマンドパラメーターを使用して、コレクション内の各値を関連付けます。PowerShell associates each value in the collection with a command parameter. Splatted パラメーターの値は、標準の変数と同じように、名前付きのスプラッティング変数に格納されますが、ドル記号 () ではなくアットマーク () で始まり @ $ ます。Splatted parameter values are stored in named splatting variables, which look like standard variables, but begin with an At symbol (@) instead of a dollar sign ($). At 記号は、単一の値ではなく、値のコレクションを渡すことを PowerShell に指示します。The At symbol tells PowerShell that you are passing a collection of values, instead of a single value.

スプラッティングを使用すると、コマンドが短く、読みやすくなります。Splatting makes your commands shorter and easier to read. さまざまなコマンド呼び出しでスプラッティング値を再利用し、スプラッティングを使用して、 $PSBoundParameters 自動変数から他のスクリプトや関数にパラメーター値を渡すことができます。You can reuse the splatting values in different command calls and use splatting to pass parameter values from the $PSBoundParameters automatic variable to other scripts and functions.

Windows PowerShell 3.0 以降では、スプラッティングを使用してコマンドのすべてのパラメーターを表すこともできます。Beginning in Windows PowerShell 3.0, you can also use splatting to represent all parameters of a command.

構文Syntax

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

パラメーター名を必要としない、位置指定パラメーターのパラメーター値を指定するには、配列構文を使用します。To provide parameter values for positional parameters, in which parameter names are not required, use the array syntax. パラメーターの名前と値のペアを指定するには、ハッシュテーブルの構文を使用します。To provide parameter name and value pairs, use the hash table syntax. Splatted の値は、パラメーターリスト内の任意の場所に配置できます。The splatted value can appear anywhere in the parameter list.

スプラッティングの場合、すべてのパラメーターを渡すためにハッシュテーブルまたは配列を使用する必要はありません。When splatting, you do not need to use a hash table or an array to pass all parameters. スプラッティングを使用していくつかのパラメーターを渡し、位置またはパラメーター名で他のパラメーターを渡すことができます。You may pass some parameters by using splatting and pass others by position or by parameter name. また、複数のオブジェクトを1つのコマンドで記号して、各パラメーターに対して複数の値を渡すことはできません。Also, you can splat multiple objects in a single command so you don't pass more than one value for each parameter.

PowerShell 7.1 では、コマンドでパラメーターを明示的に定義することによって、splatted パラメーターをオーバーライドできます。As of PowerShell 7.1, you can override a splatted parameter by explicitly defining a parameter in a command.

スプラッティングとハッシュテーブルSplatting with hash tables

ハッシュテーブルを使用して、パラメーターの名前と値のペアを記号します。Use a hash table to splat parameter name and value pairs. この形式は、位置指定パラメーターやスイッチパラメーターなど、すべてのパラメーターの型に対して使用できます。You can use this format for all parameter types, including positional and switch parameters. 位置指定パラメーターは名前で割り当てる必要があります。Positional parameters must be assigned by name.

次の例では、 Copy-Item Test.txt ファイルを同じディレクトリ内の Test2.txt ファイルにコピーする2つのコマンドを比較します。The following examples compare two Copy-Item commands that copy the Test.txt file to the Test2.txt file in the same directory.

最初の例では、パラメーター名が含まれている従来の形式を使用します。The first example uses the traditional format in which parameter names are included.

Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf

2番目の例では、ハッシュテーブルスプラッティングを使用します。The second example uses hash table splatting. 最初のコマンドは、パラメーター名とパラメーター値のペアのハッシュテーブルを作成し、変数に格納し $HashArguments ます。The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the $HashArguments variable. 2番目のコマンドは、 $HashArguments スプラッティングを使用してコマンド内の変数を使用します。The second command uses the $HashArguments variable in a command with splatting. At 記号 () は、 @HashArguments コマンドのドル記号 () に代わるもの $HashArguments です。The At symbol (@HashArguments) replaces the dollar sign ($HashArguments) in the command.

WhatIf スイッチパラメーターの値を指定するには、 $True またはを使用 $False します。To provide a value for the WhatIf switch parameter, use $True or $False.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
  WhatIf = $true
}
Copy-Item @HashArguments

注意

最初のコマンドでは、アットマーク ( @ ) は splatted 値ではなくハッシュテーブルを示します。In the first command, the At symbol (@) indicates a hash table, not a splatted value. PowerShell のハッシュテーブルの構文は次のとおりです。 @{<name>=<value>; <name>=<value>; ...}The syntax for hash tables in PowerShell is: @{<name>=<value>; <name>=<value>; ...}

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

配列を使用して、パラメーター名を必要としない位置指定パラメーターの値を記号します。Use an array to splat values for positional parameters, which do not require parameter names. 値は、配列内の位置番号の順序で指定する必要があります。The values must be in position-number order in the array.

次の例では、 Copy-Item Test.txt ファイルを同じディレクトリ内の Test2.txt ファイルにコピーする2つのコマンドを比較します。The following examples compare two Copy-Item commands that copy the Test.txt file to the Test2.txt file in the same directory.

最初の例では、パラメーター名が省略されている従来の形式を使用します。The first example uses the traditional format in which parameter names are omitted. パラメーター値は、コマンドの位置の順序で表示されます。The parameter values appear in position order in the command.

Copy-Item "test.txt" "test2.txt" -WhatIf

2番目の例では、配列スプラッティングを使用します。The second example uses array splatting. 最初のコマンドは、パラメーター値の配列を作成し、変数に格納し $ArrayArguments ます。The first command creates an array of the parameter values and stores it in the $ArrayArguments variable. 値は、配列内の位置の順序になっています。The values are in position order in the array. 2番目のコマンドは、 $ArrayArguments スプラッティングのコマンドで変数を使用します。The second command uses the $ArrayArguments variable in a command in splatting. At 記号 () は、 @ArrayArguments コマンドのドル記号 () に代わるもの $ArrayArguments です。The At symbol (@ArrayArguments) replaces the dollar sign ($ArrayArguments) in the command.

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf

ArgumentList パラメーターの使用Using the ArgumentList parameter

いくつかのコマンドレットには、コマンドレットによって実行されるスクリプトブロックにパラメーター値を渡すために使用される ArgumentList パラメーターがあります。Several cmdlets have an ArgumentList parameter that is used to pass parameter values to a script block that is executed by the cmdlet. ArgumentList パラメーターは、スクリプトブロックに渡される値の配列を受け取ります。The ArgumentList parameter takes an array of values that is passed to the script block. PowerShell は、実際には配列スプラッティングを使用して、値をスクリプトブロックのパラメーターにバインドします。PowerShell is effectively using array splatting to bind the values to the parameters of the script block. ArgumentList を使用する場合、1つのパラメーターにバインドされた単一のオブジェクトとして配列を渡す必要がある場合は、配列を別の配列の唯一の要素としてラップする必要があります。When using ArgumentList , if you need to pass an array as a single object bound to a single parameter, you must wrap the array as the only element of another array.

次の例には、文字列の配列である1つのパラメーターを受け取るスクリプトブロックが含まれています。The following example has a script block that takes a single parameter that is an array of strings.

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
  } -ArgumentList $array

この例では、の最初の項目だけ $array がスクリプトブロックに渡されます。In this example, only the first item in $array is passed to the script block.

Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)

この例では、配列 $array 全体が単一のオブジェクトとしてスクリプトブロックに渡されるように、が配列にラップされています。In this example, $array is wrapped in an array so that the entire array is passed to the script block as a single object.

Hello World!

Examples

例 1: 異なるコマンドで splatted パラメーターを再利用するExample 1: Reuse splatted parameters in different commands

この例では、さまざまなコマンドで splatted 値を再利用する方法を示します。This example shows how to reuse splatted values in different commands. この例のコマンドは、コマンドレットを使用して、 Write-Host ホストプログラムコンソールにメッセージを書き込みます。The commands in this example use the Write-Host cmdlet to write messages to the host program console. スプラッティングを使用して、前景色と背景色を指定します。It uses splatting to specify the foreground and background colors.

すべてのコマンドの色を変更するには、変数の値を変更するだけ $Colors です。To change the colors of all commands, just change the value of the $Colors variable.

最初のコマンドは、パラメーター名と値のハッシュテーブルを作成し、そのハッシュテーブルを変数に格納し $Colors ます。The first command creates a hash table of parameter names and values and stores the hash table in the $Colors variable.

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

2番目と3番目のコマンドは、 $Colors コマンドでスプラッティングの変数を使用し Write-Host ます。The second and third commands use the $Colors variable for splatting in a Write-Host command. を使用するには $Colors variable 、ドル記号 ( $Colors ) をアットマーク () に置き換え @Colors ます。To use the $Colors variable, replace the dollar sign ($Colors) with an At symbol (@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 を使用してパラメーターを転送するExample 2: Forward parameters using $PSBoundParameters

この例では、スプラッティングと自動変数を使用して、他のコマンドにパラメーターを転送する方法を示し $PSBoundParameters ます。This example shows how to forward their parameters to other commands by using splatting and the $PSBoundParameters automatic variable.

$PSBoundParameters自動変数は、スクリプトまたは関数の実行時に使用されるすべてのパラメーター名と値を含むディクショナリオブジェクト (system.string) です。The $PSBoundParameters automatic variable is a dictionary object (System.Collections.Generic.Dictionary) that contains all the parameter names and values that are used when a script or function is run.

次の例では、変数を使用して、 $PSBoundParameters スクリプトまたは関数に渡されたパラメーター値を関数から Test2 関数に転送し Test1 ます。In the following example, we use the $PSBoundParameters variable to forward the parameters values passed to a script or function from Test2 function to the Test1 function. から関数を呼び出すと、 Test1 Test2 スプラッティングが使用されます。Both calls to the Test1 function from Test2 use 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

例 3: 明示的に定義されたパラメーターを使用して splatted パラメーターをオーバーライドするExample 3: Override splatted parameters with explicitly defined parameters

この例では、明示的に定義されたパラメーターを使用して splatted パラメーターをオーバーライドする方法を示します。This example shows how to override a splatted parameter using explicitly defined parameters. これは、新しいハッシュテーブルを作成したり、記号に使用しているハッシュテーブルの値を変更したりする必要がない場合に便利です。This is useful when you don't want to build a new hashtable or change a value in the hashtable you are using to splat.

変数には、 $commonParams 仮想マシンを作成するためのパラメーターが保存されて East US います。The $commonParams variable stores the parameters to create virtual machines in the East US location. 変数は、 $allVms 作成する仮想マシンの一覧です。The $allVms variable is a list of virtual machines to create. リストをループ処理し、を使用して $commonParams 各仮想マシンを作成するためのパラメーターを記号します。We loop through the list and use $commonParams to splat the parameters to create each virtual machine. ただし、 myVM2 他の仮想マシンとは別のリージョンに作成する必要があります。However, we want myVM2 to be created in a different region than the other virtual machines. では、ハッシュテーブルを調整するのではなく $commonParams 、の 場所 パラメーターを明示的に定義して、の New-AzVm キーの値を置き換えることができ Location $commonParams ます。Instead of adjusting the $commonParams hashtable, you can explicitly define the Location parameter in New-AzVm to supersede the value of the Location key in $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
    }
}

スプラッティングコマンドのパラメーターSplatting command parameters

スプラッティングを使用して、コマンドのパラメーターを表すことができます。You can use splatting to represent the parameters of a command. この手法は、プロキシ関数、つまり別のコマンドを呼び出す関数を作成するときに便利です。This technique is useful when you are creating a proxy function, that is, a function that calls another command. この機能は、Windows PowerShell 3.0 で導入されました。This feature is introduced in Windows PowerShell 3.0.

コマンドのパラメーターを記号するには、 @Args を使用してコマンドパラメーターを表します。To splat the parameters of a command, use @Args to represent the command parameters. この手法は、コマンドパラメーターを列挙するよりも簡単です。呼び出されたコマンドのパラメーターが変更された場合でも、リビジョンなしで動作します。This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change.

この機能は、 $Args 割り当てられていないすべてのパラメーター値を含む自動変数を使用します。The feature uses the $Args automatic variable, which contains all unassigned parameter values.

たとえば、次の関数は、 Get-Process コマンドレットを呼び出します。For example, the following function calls the Get-Process cmdlet. この関数では、は、 @Args コマンドレットのすべてのパラメーターを表し Get-Process ます。In this function, @Args represents all the parameters of the Get-Process cmdlet.

function Get-MyProcess { Get-Process @Args }

関数を使用すると、 Get-MyProcess 次のコマンドに示すように、割り当てられていないすべてのパラメーターとパラメーター値がに渡され @Args ます。When you use the Get-MyProcess function, all unassigned parameters and parameter values are passed to @Args, as shown in the following commands.

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パラメーターを明示的に宣言した関数でを使用できます。You can use @Args in a function that has explicitly declared parameters. 関数内で複数回使用できますが、 @Args 次の例に示すように、入力したすべてのパラメーターがのすべてのインスタンスに渡されます。You can use it more than once in a function, but all parameters that you enter are passed to all instances of @Args, as shown in the following example.

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)

メモNotes

構成 属性またはパラメーター属性を使用 して関数を高度な関数に Parameter すると、 $args 自動変数は関数で使用できなくなります。If you make a function into an advanced function by using either the CmdletBinding or Parameter attributes, the $args automatic variable is no longer available in the function. 高度な関数には、明示的なパラメーター定義が必要です。Advanced functions require explicit parameter definition.

PowerShell Desired State Configuration (DSC) は、スプラッティングを使用するように設計されていません。PowerShell Desired State Configuration (DSC) was not designed to use splatting. スプラッティングを使用して、DSC リソースに値を渡すことはできません。You cannot use splatting to pass values into a DSC resource. 詳細については、「 スプラッティング DSC リソース」を参照してください。For more information, see Gael Colas' article Pseudo-Splatting DSC Resources.

関連項目See also

about_Arraysabout_Arrays

about_Automatic_Variablesabout_Automatic_Variables

about_Hash_Tablesabout_Hash_Tables

about_Parametersabout_Parameters