about_Parameters

適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0

トピック

about_Parameters

概要

Windows PowerShell のコマンド パラメーターを使用する方法について説明します。

詳細説明

コマンドレット、関数、スクリプトなど、Windows PowerShell のほとんどのコマンドでは、オプションの選択や入力値の指定にパラメーターを使用します。パラメーターは、コマンド名の後に次の形式で記述します。

        -<parameter_name> <parameter_value>

パラメーターの名前の前にはハイフン (-) を付けます。これは、ハイフンに続く単語がパラメーター名であることを Windows 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」を参照してください。

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

Get-Help コマンドレットで Full、Parameter、または Online パラメーターを使用すると、パラメーターに関する詳細な情報が記載されたパラメーター属性テーブルが表示されます。

この情報には、パラメーターを使用する際に知っておく必要がある詳しい情報が含まれます。たとえば、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?                    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 ではパラメーター名が不要ですが、パラメーター値はコマンド内で最初の、または唯一の名前のないパラメーター値である必要があります。一方、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?

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

    
    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.


                             When a parameter is "True (by Value)", Windows 
                             PowerShell tries to associate any piped values 
                             with that parameter before it tries other methods
                             to interpret the command.


    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.
 
                             For example, you can pipe a value to a Name 
                             parameter only when the value has a property 
                             called "Name".

Accepts Wildcard Characters?

この設定は、パラメーター値にワイルドカード文字を使用して、ターゲット コンテナー内の複数の既存の項目と照合できるかどうかを示します。

共通パラメーター

共通パラメーターとは、すべてのコマンドレットで使用できるパラメーターです。共通パラメーターの詳細については、「about_CommonParameters」を参照してください。

関連項目

about_Command_syntax

about_Comment_Based_Help

about_Functions_Advanced

about_Parameters_Default_Values

about_Pipelines

about_Wildcards