トピック
about_Parameters
簡易説明
Windows PowerShell でコマンドレット パラメーターを使用する方法について説明します。
詳細説明
ほとんどの Windows PowerShell コマンドレットおよび関数で、オプションの選択や設定の
入力にはパラメーターが使用されます。パラメーターは、コマンドレット名または関数名の
後ろに置かれ、一般的に次のような形式で入力されます。
-<parameter_name> <parameter_value>
パラメーター名の前にはハイフン (-) を付けます。これにより、ハイフンに続く単語は
パラメーターであり、コマンドレットまたは関数に渡す値ではないことを示します。
すべてのパラメーターに値を設定する必要はなく、すべてのパラメーター名を指定する
必要もありません。パラメーター名が暗黙的に指定されているため、コマンドに含める必要が
ない場合があります。
パラメーターの型と要件は、コマンドまたは関数のどちらに使用されるかで決まります。
また、コマンドレットの種類によっても異なります。コマンドレットのパラメーターに関する詳細は、
Get-Help コマンドレットを使用して参照できます。たとえば、Get-ChildItem コマンドレットの
パラメーターの詳細を表示するには、次のように入力します。
get-help get-childitem
関数のパラメーターの詳細を調べるには、パラメーターの定義を確認します。
パラメーターは、関数名のすぐ後または関数の本体で、Param キーワードに
より定義されています。詳細については、「about_Functions」を参照してください。
一部の関数には、パラメーターに関するコメントベースのヘルプも含まれています。
これらのヘルプを参照するには、Get-Help コマンドレットをこれらの関数と一緒に
使用します。詳細については、Get-Help および about_Comment_Based_Help の
ヘルプ トピックを参照してください。
Get-Help コマンドレットは、コマンドレットまたは関数に関するさまざまな詳細情報
を返します。これには、コマンドレットまたは関数の説明、コマンド構文、パラメー
ターの詳細、およびコマンドレットまたは関数の使い方を示す例が含まれています。
Get-Help コマンドレットまたは関数の Parameter パラメーターを使用して、特定の
パラメーターに関する情報が取得できます。または、Parameter パラメーターに
ワイルドカード文字 (*) を使用して、コマンドレットまたは関数のすべての
パラメーターに関する情報を取得することもできます。たとえば、Get-Member
コマンドレットまたは関数のすべてのパラメーターに関する情報を取得するには、
次のように入力します。
get-help get-member -parameter *
この情報には、パラメーターを使用する際に必要になる詳細な情報が含まれています。
たとえば、Get-ChildItem コマンドレットのヘルプ トピックには、Path
パラメーターに関する次のような詳細情報が含まれています。
-path <string[]>
場所のパスを 1 つ以上指定します。ワイルドカード文字を使用できます。
既定の場所は現在のディレクトリ (.) です。
Required? false
Position? 1
Default value Current directory
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? true
パラメーター情報には、パラメーターの構文、パラメーターの説明、
パラメーターの属性に関する情報が含まれています。以下の
セクションでは、各パラメーター属性について説明します。
Parameter Required?
パラメーターが必須かどうか、つまりこのコマンドレットを使用するすべての
コマンドにこのパラメーターを含める必要があるかどうかを指定します。
値が "True" の場合、コマンドでこのパラメーターが指定されていないと、
Windows PowerShell によってこのパラメーターの値の入力を求める
メッセージが表示されます。
Parameter Position?
パラメーター名を省略してパラメーター値を指定できるかどうかを指定します。
"0" または "named" に設定されている場合は、パラメーター名が必要です。
この種のパラメーターは、名前付きパラメーターと呼ばれます。名前付き
パラメーターは、コマンドレット名の後ろの任意の位置に列挙できます。
"Parameter position?" の設定が 0 以外の整数に設定されている場合は、
パラメーター名を省略できます。この種のパラメーターは位置指定
パラメーターと呼ばれており、数字はそのパラメーターと他の位置指定
パラメーターとの位置関係を表します。位置指定パラメーターの
パラメーター名を含める場合は、コマンドレット名の後ろの任意の位置
にパラメーターを列挙できます。
たとえば、Get-ChildItem コマンドレットには、Path パラメーターと
Exclude パラメーターがあります。Path の "Parameter position?" の
設定が 1 の場合は、Path が位置指定パラメーターであることを意味します。
Exclude の "Parameter position?" の設定が 0 の場合は、Exclude が
名前付きパラメーターであることを意味します。
これは、Path にはパラメーター名を付ける必要がないことを意味しています。
ただし、パラメーター値が最初に現れるか、名前のないパラメーターの値が
コマンドに 1 つしか存在しないことが必須です。Exclude は名前付き
パラメーターであるため、コマンドの任意の場所に配置できます。
この 2 つのパラメーターに関する "Parameter 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
別の位置指定パラメーターをパラメーター名を付けずに含める場合は、
"Parameter position?" 設定で指定された順序でそのパラメーターを
配置する必要があります。
Parameter Type
パラメーター値の Microsoft .NET Framework 型を指定します。たとえば、
型が Int32 の場合は、パラメーター値が整数である必要があります。
また、型が string の場合は、パラメーター値が文字列である必要があります。
文字列にスペースが含まれている場合は、値を引用符で囲むか、またはス
ペースの前にエスケープ文字 (`) を付ける必要があります。
Default Value
他の値を指定しなかった場合に、パラメーターに設定する値を指定します。
たとえば、Path パラメーターの既定値は、多くの場合、現在のディレクトリです。
必須パラメーターの場合、既定値は存在しません。多くのオプションのパラメーターに
も既定値は存在しません。これは、これらのパラメーターが使用されないときは、
効力がないためです。
Accepts Multiple Values?
パラメーターが複数のパラメーター値を受け入れるかどうかを指定します。
パラメーターが複数の値を受け入れる場合は、コマンドでコンマ区切りの
一覧を入力してその一覧をパラメーター値とするか、コンマ区切りの一覧
(配列) を変数に格納してその変数をパラメーター値として指定することができます。
たとえば、Get-Service コマンドレットの ServiceName パラメーターは、
複数の値を受け入れます。次のコマンドはどちらも有効です。
get-service -servicename winrm, netlogon
$s = "winrm", "netlogon"
get-service -servicename $s
Accepts Pipeline Input?
パイプライン演算子 (|) を使用して、パラメーターに値を渡すことができるかどうかを指定します。
値 説明
----- -----------
False パイプを使用して値をパラメーターに渡すことはできません。
True (by Value) パイプを使用して任意の値をパラメーターに渡すことができます。
ただし、値の NET Framework 型がパラメーターに指定されている
NET Framework 型と一致するか、指定された .NET Framework 型に
値を変換できる場合に限ります。
パラメーターが "True (by Value)" の場合、Windows PowerShell
では、他のメソッドを使用してコマンドの解釈を行う前に、パイプ
処理されたすべての値をパラメーターに関連付けます。
True (by Property Name) パイプを使用して値をパラメーターに渡すことができます。ただし、
パラメーターと同じ名前のプロパティがパラメーターの NET Framework
型に含まれている必要があります。
たとえば、パイプを使用して Name パラメーターに値を渡す場合には、
値に "Name" という名前のプロパティが含まれている必要があります。
Accepts Wildcard Characters?
ターゲット コンテナー内の既存の複数の項目と一致するように、パラメーター値にワイルドカード
文字を含めることができるかどうかを指定します。
共通パラメーター
共通パラメーターとは、すべてのコマンドレットで使用することができるパラメーターのことです。
共通パラメーターの詳細について参照するには、次のように入力します。
help about_commonparameters
関連項目
about_Command_syntax
about_Comment_Based_Help
about_Functions_Advanced
about_Pipelines
about_Wildcards