パラメータについて

簡単な説明

PowerShell でコマンドパラメーターを操作する方法について説明します。

長い説明

コマンドレット、関数、スクリプトなどのほとんどの PowerShell コマンドは、パラメーターに依存することで、ユーザーがオプションを選択したり入力を提供したりできるようにします。パラメーターはコマンド名に従い、次の形式になります。

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

パラメーターの名前の前にはハイフン (-) が付き、ハイフンに続く単語がパラメーター名であることを PowerShell に通知します。パラメーターの名前と値は、スペースまたはコロンで区切ることができます。一部のパラメーターではパラメーター値を必要とせず、受け入れることもありません。その他のパラメーターには値が必要ですが、コマンドにパラメーター名は必要ありません。

パラメーターの種類と、それらのパラメーターの要件は異なります。コマンドのパラメーターに関する情報を検索するには、Get-Help コマンドレットを使用します。たとえば、Get-ChildItem コマンドレットのパラメーターに関する情報を検索するには、次のように入力します。

Get-Help Get-ChildItem

スクリプトのパラメーターに関する情報を検索するには、スクリプトファイルへの完全なパスを使用します。例えば次が挙げられます。

Get-Help $home\Documents\Scripts\Get-Function.ps1

Get-Help コマンドレットは、説明、コマンド構文、パラメーターに関する情報、およびコマンドでパラメーターを使用する方法を示す例など、コマンドに関するさまざまな詳細を返します。

Get-Help コマンドレットの Parameter パラメーターを使用して、特定のパラメーターに関する情報を検索することもできます。または、Parameter パラメーターとワイルドカード文字 (*) 値を使用して、コマンドのすべてのパラメーターに関する情報を検索できます。たとえば、次のコマンドでは、Get-Member コマンドレットのすべてのパラメーターに関する情報を取得します。

Get-Help Get-Member -Parameter *

既定のパラメーター値

省略可能なパラメーターには既定値があります。これは、コマンドでパラメーターが指定されていない場合に使用または想定される値です。

たとえば、多くのコマンドレットの ComputerName パラメーターの既定値はローカルコンピューターの名前です。その結果、ComputerName パラメーターが指定されていない限り、コマンドではローカルコンピューター名が使用されます。

既定のパラメーター値を見つけるには、コマンドレットのヘルプトピックを参照してください。パラメーターの説明には既定値を含める必要があります。

コマンドレットまたは高度な関数の任意のパラメーターにカスタムの既定値を設定することもできます。カスタムの既定値の設定については、「about_Parameters_Default_Values」を参照してください。

パラメーター属性テーブル

コマンドレットの Full、Parameter、Get-Help のいずれかのパラメーターを使用すると、Get-Help にはパラメーター属性テーブルとともにパラメーターに関する詳細情報が表示されます。

この情報には、パラメーターを使用するために知る必要がある詳細が含まれます。たとえば、Get-ChildItem コマンドレットのヘルプトピックには、その Path パラメーターに関する次の詳細が含まれています。

-path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

パラメーター情報には、パラメーター構文、パラメーターの説明、およびパラメーター属性が含まれています。以降のセクションではパラメーター属性について説明します。

必須のパラメーター

この設定は、パラメーターが必須かどうか、つまり、このコマンドレットを使用するすべてのコマンドにこのパラメーターを含める必要があるかどうかを示します。値が True で、パラメーターがコマンドに指定されていない場合、PowerShell はパラメーターの値を求めるメッセージを表示します。

パラメーターの位置

Position設定が正の整数に設定されている場合、パラメータ名は必須ではありません。この型のパラメーターは位置指定パラメーターと呼ばれ、数値は他の位置指定パラメーターに対してパラメーターを表示する必要がある位置を示します。名前付きパラメーターは、コマンドレット名の後の任意の位置に一覧表示できます。位置指定パラメーターのパラメーター名を含める場合は、コマンドレット名の後の任意の位置にパラメーターを一覧表示できます。

たとえば、Get-ChildItem コマンドレットには Path パラメーターと Exclude パラメーターがあります。 Position の設定は 0 で、これは位置指定パラメーターであることを意味します。 Position の設定には、名前が付いています。

つまり、Path ではパラメーター名は必要ありませんが、そのパラメーター値はコマンドの最初のパラメーター値または名前のないパラメーター値である必要があります。ただし、Exclude パラメーターは名前付きパラメーターであるため、コマンド内の任意の位置に配置できます。

これら 2 つのパラメーターの Position 設定の結果として、次のいずれかのコマンドを使用できます。

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

パラメーター名を含めずに別の位置指定パラメーターを含める場合、そのパラメーターは、Position 設定で指定された順序で配置する必要があります。

パラメーターの型

この設定では、パラメーター値の Microsoft .NET Framework 型を指定します。たとえば、型が Int32 の場合、パラメーター値は整数である必要があります。型が文字列の場合、パラメーター値は文字列である必要があります。文字列にスペースが含まれている場合は、値を引用符で囲むか、スペースの前にエスケープ文字 ( ' ) を付ける必要があります。

デフォルト値

この設定では、他の値が指定されていない場合にパラメーターが想定する値を指定します。たとえば、Path パラメーターの既定値は多くの場合、現在のディレクトリです。必須パラメーターに既定値が設定されることはありません。多くの省略可能なパラメーターでは、パラメーターが使用されていない場合は効果がないため、既定値はありません。

複数の値を受け入れる

この設定は、パラメーターが複数のパラメーター値を受け入れるかどうかを示します。パラメーターが複数の値を受け入れる場合は、コマンドのパラメーターの値としてコンマ区切りリストを入力することも、変数にコンマ区切りリスト (配列) を保存してから、パラメーター値として変数を指定することもできます。

たとえば、 Get-Service コマンドレットの ServiceName パラメーターは、複数の値を受け入れます。次のコマンドはどちらも有効です。

Get-Service -servicename winrm, netlogon

$s = "winrm", "netlogon"
Get-Service -servicename $s

パイプライン入力を受け入れる

この設定は、パイプライン演算子 ( | ) を使用してパラメーターに値を送信できるかどうかを示します。

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

パラメーターが "True (by Value)" の場合、PowerShell は、他のメソッドがコマンドを解釈する前に、パイプされた値をそのパラメーターに関連付けようとします。

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

たとえば、値に Name というプロパティが含まれている場合にのみ、Name パラメーターに値をパイプできます。

注

パイプライン入力 (by Value) または (by PropertyName) を受け入れる型指定されたパラメーターでは、パラメーターで delay-bind スクリプトブロックを使用できます。

遅延バインド用のスクリプトブロックは、ParameterBindingの間に自動的に実行されます。結果はパラメーターにバインドされます。遅延バインディングは、型または ScriptBlock として定義されたパラメーターでは機能System.Object。スクリプトブロックは、呼び出されることなく渡されます。

こちらで遅延バインド スクリプトブロック について読むことができます：about_Script_Blocks.md