about_Functions_Advanced_Parameters

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

トピック

ここにセクションの本文を挿入してください。

概要

高度な関数にパラメーターを追加する方法について説明します。

詳細説明

独自に記述する高度な関数にパラメーターを追加し、パラメーターの属性および引数を使用して、関数のユーザーがパラメーターで渡すパラメーター値を制限することができます。

ユーザーは、Windows PowerShell® によりすべてのコマンドレットおよび高度な関数に自動的に追加された共通パラメーターに加えて、独自に関数に追加されたパラメーターも使用できます。Windows PowerShell 共通パラメーターの詳細については、「about_CommonParameters」(https://go.microsoft.com/fwlink/?LinkID=113216) を参照してください。

Windows PowerShell 3.0 以降では、スプラッティングを @Args と共に使用して、コマンド内のパラメーターを表することができます。この手法は、単純かつ高度な関数で有効です。詳細については、「about_Functions」(https://go.microsoft.com/fwlink/?LinkID=113231) および「about_Splatting」(https://go.microsoft.com/fwlink/?LinkID=262720) を参照してください。

静的パラメーター

静的パラメーターは、関数で常に使用できるパラメーターです。Windows PowerShell のコマンドレットおよびスクリプトのパラメーターのほとんどは静的パラメーターです。

次の例では、次の特性を備えた ComputerName パラメーターの宣言を示します。

必須です。

パイプラインから入力を受け取ります。

入力として文字列の配列を受け取ります。

        Param
          (
            [parameter(Mandatory=$true,
            ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

パラメーターの属性

このセクションでは、関数のパラメーターに追加できる属性について説明します。

属性はすべてオプションです。ただし、CmdletBinding 属性を省略した場合、高度な関数として認識されるには、関数に Parameter 属性を含める必要があります。

パラメーターの宣言ごとに、1 つ以上の属性を追加できます。パラメーターの宣言に追加できる属性の数に制限はありません。

Parameter 属性

Parameter 属性を使用して、関数のパラメーターの属性を宣言します。

Parameter 属性はオプションで、関数のどのパラメーターにも属性が不要な場合は省略できますが、(単純な関数ではなく) 高度な関数として認識されるようにするには、関数に CmdletBinding 属性または Parameter 属性、あるいはその両方が必要です。

Parameter 属性には、パラメーターが必須かオプションかなど、パラメーターの特性を定義する引数があります。

次の構文を使用して、Parameter 属性、引数、および引数の値を宣言します。引数とその値を囲むかっこは、"Parameter" の後にスペースを入れずに続ける必要があります。

        Param
          (
            [parameter(Argument=value)]
            $ParameterName
          )

かっこ内の引数を区切るには、コンマを使用します。次の構文を使用して、Parameter 属性の 2 つの引数を宣言します。

        Param
          (
            [parameter(Argument1=value1,
                       Argument2=value2)]

          )

(CmdletBinding 属性を使用する代わりとして) 引数なしの Parameter 属性を使用する場合も、属性名の後にかっこを続ける必要があります。

        Param
          (
            [parameter()]
            $ParameterName
          )

Mandatory 引数

Mandatory 引数は、パラメーターが必須であることを示します。この引数が指定されていない場合、パラメーターはオプション パラメーターです。

次の例では、ComputerName パラメーターを宣言します。Mandatory 引数を使用して、パラメーターを必須にしています。

        Param
          (
            [parameter(Mandatory=$true)]
            [String[]]
            $ComputerName
          )

Position 引数

Position 引数は、パラメーターをコマンド内で使用するときに、パラメーター名が必要かどうかを決定します。パラメーター宣言に Position 引数が含まれている場合、パラメーター名を省略できます。名前のないパラメーターの値は、Windows PowerShell により、コマンド内の名前のないパラメーターの値の一覧から、その位置 (または順序) によって識別されます。

Position 引数が指定されていない場合は、コマンドでパラメーターを使用するときに、常にパラメーター名 (またはパラメーター名のエイリアスか省略形) をパラメーター値の前に記述する必要があります。

既定では、関数のパラメーターはすべて位置指定ができます。Windows PowerShell は、パラメーターが関数で宣言されている順序でパラメーターに位置番号を割り当てます。この機能を無効にするには、CmdletBinding 属性の PositionalBinding 引数の値を $False に設定します。Position 引数は、Position 引数が宣言されているパラメーターの PositionalBinding 引数の値よりも優先されます。詳細については、「about_Functions_CmdletBindingAttribute」の「PositionalBinding」を参照してください。

Position 引数の値は、整数で指定します。位置の値 0 はコマンド内の最初の位置を表し、位置の値 1 はコマンド内の 2 番目の位置を表すというように続きます。

関数に位置指定のパラメーターがない場合、Windows PowerShell は、パラメーターの宣言の順序に基づいて、各パラメーターに位置を割り当てます。ただし、ベスト プラクティスとして、この割り当てには依存しないでください。パラメーターを位置指定する場合は、Position 引数を使用します。

次の例では、ComputerName パラメーターを宣言します。ここでは、値 0 の Position 引数を使用します。その結果、コマンドから "-ComputerName" を省略した場合、その値は、コマンド内の最初または唯一の名前のないパラメーターの値になります。

        Param
          (
            [parameter(Position=0)]
            [String[]]
            $ComputerName
          )

注記:

Get-Help コマンドレットで対応する "Position?" パラメーター属性が表示される場合、位置の値は 1 増加されます。たとえば、Position 引数の値が 0 のパラメーターでは、パラメーター属性は "Position? 1" になります。

ParameterSetName 引数

ParameterSetName 引数では、パラメーターが属するパラメーター セットを指定します。パラメーター セットを指定しない場合、パラメーターは、関数で定義されているすべてのパラメーター セットに属します。したがって、一意にするために、各パラメーター セットに他のパラメーター セットのメンバーではないパラメーターが少なくとも 1 つ必要です。

次の例では、Computer パラメーター セットの ComputerName パラメーター、User パラメーター セットの UserName パラメーター、および両方のパラメーター セットの Summary パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false)]
            [Switch]
            $Summary
          )

引数ごとに 1 つの ParameterSetName 値のみ、および Parameter 属性ごとに 1 つの ParameterSetName 引数のみを指定できます。パラメーターが複数のパラメーター セットに出現することを示すには、Parameter 属性を追加します。

次の例では、Computer および User パラメーター セットに Summary パラメーターを明示的に追加します。Summary パラメーターは、1 つのパラメーター セットでは必須で、もう 1 つのパラメーター セットではオプションになっています。

        Param
          (
            [parameter(Mandatory=$true,
                      ParameterSetName="Computer")]
            [String[]]
            $ComputerName,

            [parameter(Mandatory=$true,
                      ParameterSetName="User")]
            [String[]]
            $UserName,

            [parameter(Mandatory=$false, ParameterSetName="Computer")]
            [parameter(Mandatory=$true, ParameterSetName="User")]
            [Switch]
            $Summary
          )
        

パラメーター セットの詳細については、MSDN ライブラリの「コマンドレットのパラメーター セット」(https://go.microsoft.com/fwlink/?LinkId=142183) を参照してください。

ValueFromPipeline 引数

ValueFromPipeline 引数は、パラメーターがパイプライン オブジェクトから入力を受け取ることを示します。関数で、オブジェクトのプロパティのみでなく、オブジェクト全体を受け取る場合は、この引数を指定します。

次の例では、パイプラインから関数に渡されたオブジェクトを受け取る、必須の ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipeline=$true)]
            [String[]]
            $ComputerName
          )

ValueFromPipelineByPropertyName 引数

ValueFromPipelineByPropertyName 引数は、パラメーターがパイプライン オブジェクトのプロパティから入力を受け取ることを示します。オブジェクトのプロパティには、パラメーターと同じ名前またはエイリアスが必要です。

たとえば、関数に ComputerName パラメーターがあり、パイプされたオブジェクトに ComputerName プロパティがある場合、ComputerName プロパティの値が関数の ComputerName パラメーターに割り当てられます。

次の例では、パイプラインを介して関数に渡されるオブジェクトの ComputerName プロパティから入力を受け取る、必須の ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromPipelineByPropertyName=$true)]
            [String[]]
            $ComputerName
          )

ValueFromRemainingArguments 引数

ValueFromRemainingArguments 引数は、パラメーターが、関数の他のパラメーターに割り当てられていないコマンド内のすべてのパラメーター値を受け取ることを示します。

次の例では、関数に渡された残りのすべてのパラメーター値を受け取る、必須の ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true,
                      ValueFromRemainingArguments=$true)]
            [String[]]
            $ComputerName
          )

HelpMessage 引数

HelpMessage 引数では、パラメーターの簡単な説明またはその値を含む文字列を指定します。Windows PowerShell は、コマンドから必須のパラメーター値が欠けているときに表示されるプロンプトで、このメッセージを表示します。この引数は、オプションのパラメーターには影響しません。

次の例では、必須の ComputerName パラメーターと、想定されるパラメーター値を説明するヘルプ メッセージを宣言します。

        Param
          (
            [parameter(mandatory=$true,
                       HelpMessage="Enter one or more computer names separated by commas.")]
            [String[]]
            $ComputerName
          )

ALIAS 属性

Alias 属性は、パラメーターの代替名を設定します。パラメーターに割り当てできるエイリアスの数に制限はありません。

次の例では、必須の ComputerName パラメーターに "CN" と "MachineName" というエイリアスを追加するパラメーター宣言を示します。

        Param
          (
            [parameter(Mandatory=$true)]
            [alias("CN","MachineName")]
            [String[]]
            $ComputerName
          )

パラメーターと変数の検証属性

検証属性は、高度な関数が呼び出されるときに、ユーザーが渡したパラメーター値をテストするよう Windows PowerShell に指示します。パラメーター値のテストに失敗した場合、エラーが生成され、関数は呼び出されません。また、一部の検証属性を使用して、ユーザーが変数に指定できる値を制限することもできます。

AllowNull 検証属性

AllowNull 属性を使用すると、必須のパラメーターの値を null ($null) にすることができます。次の例では、Null 値を持つことができる ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowNull()]
            [String]
            $ComputerName
          )

AllowEmptyString 検証属性

AllowEmptyString 属性を使用すると、必須のパラメーターの値を空の文字列 ("") にすることができます。次の例では、空の文字列値を持つことができる ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyString()]
            [String]
            $ComputerName
          )

AllowEmptyCollection 検証属性

AllowEmptyCollection 属性を使用すると、必須のパラメーターの値を空のコレクション (@()) にすることができます。次の例では、空のコレクション値を持つことができる ComputerName パラメーターを宣言します。

        Param
          (
            [parameter(Mandatory=$true)]
            [AllowEmptyCollection()]
            [String[]]
            $ComputerName
          )

ValidateCount 検証属性

ValidateCount 属性では、パラメーターが受け取るパラメーター値の最小数と最大数を指定します。Windows PowerShell は、関数を呼び出すコマンドのパラメーター値の数が範囲外にある場合、エラーを生成します。

次のパラメーター宣言では、1 から 5 個のパラメーター値を受け取る ComputerName パラメーターが作成されます。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateCount(1,5)]
            [String[]]
            $ComputerName
          )

ValidateLength 検証属性

ValidateLength 属性では、パラメーターまたは変数の値に含まれる最小文字数と最大文字数を指定します。Windows PowerShell は、パラメーターまたは変数に指定された値の長さが範囲外にある場合、エラーを生成します。

次の例では、各コンピューターの名前は 1 から 10 文字である必要があります。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateLength(1,10)]
            [String[]]
            $ComputerName
          )

次の例では、変数 $number の値は、最小の長さが 1 文字、最大の長さが 10 文字である必要があります。

        [Int32][ValidateLength(1,10)]$number = 01

ValidatePattern 検証属性

ValidatePattern 属性では、パラメーターまたは変数の値と比較される正規表現を指定します。Windows PowerShell は、値が正規表現パターンと一致しない場合、エラーを生成します。

次の例では、パラメーターの値は 4 桁の数値で、各桁は 0 から 9 までの数字である必要があります。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidatePattern("[0-9][0-9][0-9][0-9]")]
            [String[]]
            $ComputerName
          )

次の例では、変数 $number の値は 4 桁の数値で、各桁は 0 から 9 までの数字である必要があります。

        [Int32][ValidatePattern("[0-9][0-9][0-9][0-9]")]$number = 1111

ValidateRange 検証属性

ValidateRange 属性では、各パラメーターまたは変数の値の数値の範囲を指定します。Windows PowerShell は、値が範囲外にある場合、エラーを生成します。次の例では、Attempts パラメーターの値は 0 から 10 の間である必要があります。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateRange(0,10)]
            [Int]
            $Attempts
          )

次の例では、変数 $number の値は 0 から 10 の間である必要があります。

        [Int32][ValidateRange(0,10)]$number = 5

ValidateScript 検証属性

ValidateScript 属性では、パラメーターまたは変数の値を検証するために使用するスクリプトを指定します。Windows PowerShell は値をスクリプトにパイプし、スクリプトで "false" が返された場合、またはスクリプトで例外がスローされた場合に、エラーを生成します。

ValidateScript 属性を使用するとき、検証されている値は $_ 変数にマップされます。変数 $_ を使用すると、スクリプト内の値を参照できます。

次の例では、EventDate パラメーターの値は現在の日付以降である必要があります。

        Param
          (
            [parameter()]
            [ValidateScript({$_ -ge (get-date)})]
            [DateTime]
            $EventDate
          )

次の例では、変数 $date の値は現在の日時以降である必要があります。

       [DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date)

ValidateSet 属性

ValidateSet 属性では、パラメーターまたは変数の有効な値のセットを指定します。Windows PowerShell は、パラメーターまたは変数の値がセット内の値と一致しない場合、エラーを生成します。次の例では、Detail パラメーターの値は "Low"、"Average"、または "High" のみ指定できます。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateSet("Low", "Average", "High")]
            [String[]]
            $Detail
          )

次の例では、変数 $flavor の値は Chocolate、Strawberry、または Vanilla のいずれかにする必要があります。

        [String][ValidateSet("Chocolate", "Strawberry", "Vanilla")]$flavor = Strawberry

ValidateNotNull 検証属性

ValidateNotNull 属性では、パラメーターの値を null ($null) にできないことを指定します。Windows PowerShell は、パラメーターの値が null の場合、エラーを生成します。

ValidateNotNull 属性は、パラメーター値の型が指定されていない場合、または指定された型が Null 値を受け取る場合に使用するように設計されています。(文字列などの null 値を受け取らない型を指定した場合、null 値は指定された型と一致しないため、ValidateNotNull 属性がなくても拒否されます。)

次の例では、ID パラメーターの値を null にできません。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNull()]
            $ID
          )

ValidateNotNullOrEmpty 検証属性

ValidateNotNullOrEmpty 属性では、パラメーター値を null ($null) および空の文字列 ("") にできないことを指定します。Windows PowerShell は、関数呼び出しでパラメーターが使用され、その値が null、空の文字列、または空の配列である場合に、エラーを生成します。

        Param
          (
            [parameter(Mandatory=$true)]
            [ValidateNotNullOrEmpty()]
            [String[]]
            $UserName
          )

動的パラメーター

動的パラメーターとは、特定の条件下でのみ使用可能なコマンドレット、関数、またはスクリプトのパラメーターです。

たとえば、いくつかのプロバイダー コマンドレットには、コマンドレットがプロバイダー ドライブまたはプロバイダー ドライブの特定のパスで使用される場合にのみ使用できるパラメーターがあります。たとえば、Encoding パラメーターは、Add-Content、Get-Content、および Set-Content コマンドレットがファイル システム ドライブで使用される場合にのみ、これらのコマンドレットで使用できます。

他のパラメーターが関数のコマンドで使用される場合、または他のパラメーターが特定の値を持つ場合にのみ表示されるパラメーターを作成することもできます。

動的パラメーターは便利ですが、ユーザーが見つけにくいため、必要なときにのみ使用するようにします。動的パラメーターを検索するには、ユーザーがプロバイダー パスに入り、Get-Command コマンドレットの ArgumentList パラメーターまたは Get-Help の Path パラメーターを使用する必要があります。

関数またはスクリプトの動的パラメーターを作成するには、DynamicParam キーワードを使用します。

構文は次のとおりです。

      DynamicParam {<statement-list>}

ステートメント一覧で If ステートメントを使用して、パラメーターが関数で使用可能になる条件を指定します。

New-Object コマンドレットを使用して、パラメーターを表してその名前を指定する System.Management.Automation.RuntimeDefinedParameter オブジェクトを作成します。

New-Object コマンドを使用して、Mandatory、Position、ValueFromPipeline などのパラメーターの属性またはそのパラメーター セットを表す System.Management.Automation.ParameterAttribute オブジェクトを作成することもできます。

次の例では、Name および Path という名前の標準パラメーターと、DP1 という名前のオプションの動的パラメーターを持つサンプル関数を示します。DP1 パラメーターは、PSet1 パラメーター セットに含まれ、Int32 型が設定されています。DP1 パラメーターは、HKEY_LOCAL_MACHINE レジストリ ドライブで使用されていることを示す "HKLM:" が Path パラメーターの値に含まれている場合にのみサンプル関数で使用できます。

    function Get-Sample {
        [CmdletBinding()]
        Param ([String]$Name, [String]$Path)
 
        DynamicParam
        {
            if ($path -match ".*HKLM.*:")
            {
                $attributes = new-object System.Management.Automation.ParameterAttribute
                $attributes.ParameterSetName = "__AllParameterSets"
                $attributes.Mandatory = $false
                $attributeCollection = new-object `
                    -Type System.Collections.ObjectModel.Collection[System.Attribute]
                $attributeCollection.Add($attributes)

                $dynParam1 = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection)
            
                $paramDictionary = new-object `
                    -Type System.Management.Automation.RuntimeDefinedParameterDictionary
                $paramDictionary.Add("dp1", $dynParam1)
                return $paramDictionary
            }
        }
    }

詳細については、MSDN (Microsoft Developer Network) ライブラリの「RuntimeDefinedParameter クラス」(https://go.microsoft.com/fwlink/?LinkID=145130) を参照してください。

スイッチ パラメーター

スイッチ パラメーターは、パラメーター値のないパラメーターです。これらは使用したときにのみ有効で、その作用は 1 つしかありません。

たとえば、PowerShell.exe の -NoProfile パラメーターはスイッチ パラメーターです。

関数にスイッチ パラメーターを作成するには、パラメーター定義で Switch 型を指定します。

    For example:
        Param ([Switch]<ParameterName>)
    -or- 
        Param
          (
             [parameter(Mandatory=$false)]
             [Switch]
             $<ParameterName>
          )

スイッチ パラメーターは使いやすく、構文が難しいブール型のパラメーターよりもお勧めです。

たとえば、スイッチ パラメーターを使用する場合、ユーザーはコマンドにパラメーターを入力します。

        -IncludeAll

ブール型パラメーターを使用する場合は、パラメーターとブール値を入力します。

        -IncludeAll:$true

スイッチ パラメーターを作成する場合、パラメーター名は慎重に選択します。パラメーター名でパラメーターの作用がユーザーに伝わるようにし、値が必要であることを示すようなあいまいな用語 (Filter、Maximum など) は避けます。

関連項目

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute