次の方法で共有


関数の詳細パラメーターについて

簡単な説明

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

長い説明

記述する高度な関数にパラメーターを追加し、パラメーターの属性と引数を使用して、関数ユーザーがパラメーターと共に送信するパラメーター値を制限できます。

関数に追加するパラメーターは、PowerShell がすべてのコマンドレットと高度な関数に自動的に追加する一般的なパラメーターに加えて、ユーザーが使用できます。 PowerShell の共通パラメーターの詳細については、「 about_CommonParameters」を参照してください。

PowerShell 3.0 以降では、 で @Args スプラッティングを使用して、コマンドのパラメーターを表すことができます。 スプラッティングは、シンプルで高度な機能で有効です。 詳細については、「 about_Functionsabout_Splatting」を参照してください。

静的パラメーター

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

次の例は、次の特性を持つ ComputerName パラメーターの宣言を示しています。

  • 必須です (必須)。
  • パイプラインから入力を受け取ります。
  • 文字列の配列を入力として受け取ります。
Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

パラメーターの属性

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

すべての属性は省略できます。 ただし、 CmdletBinding 属性を 省略した後、高度な関数として認識されるようにするには、関数に Parameter 属性を含める必要があります。

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

パラメーター属性

Parameter 属性は、関数パラメーターの属性を宣言するために使用されます。

Parameter 属性は省略可能であり、関数のどのパラメーターにも属性が必要ない場合は省略できます。 ただし、単純な関数ではなく、高度な関数として認識するには、関数に CmdletBinding 属性または Parameter 属性、またはその両方が必要です。

Parameter 属性には、 パラメーター の特性を定義する引数があります (パラメーターが必須か省略可能かなど)。

Parameter 属性、引数、および引数値を宣言するには、次の構文を使用します。 引数とその値を囲むかっこは 、スペースなしで Parameter に 従う必要があります。

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

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

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

引数を指定せずに Parameter 属性を使用する場合は、 CmdletBinding 属性を使用する代わりに、属性名の後に続くかっこが必要です。

Param(
    [Parameter()]
    $ParameterName
)

必須引数

引数は Mandatory 、 パラメーターが必要であることを示します。 この引数を指定しない場合、 パラメーターは省略可能です。

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

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

Position 引数

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

引数が Position 指定されていない場合、パラメーター名、またはパラメーター名の別名または省略形は、パラメーターがコマンドで使用されるたびに、パラメーター値の前に置く必要があります。

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

引数の Position 値は整数として指定されます。 位置値 0 はコマンドの最初の位置を表し、位置値 1 はコマンド内の 2 番目の位置を表します。

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

次の例では、 ComputerName パラメーターを宣言します。 値が Position0 の 引数を使用します。 その結果、 が コマンドから省略された場合 -ComputerName 、その値はコマンドの最初または唯一の名前のないパラメーター値である必要があります。

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

注意

コマンドレットに Get-Help 対応する Position パラメーター属性が表示されると、位置の値が 1 ずつインクリメントされます。

たとえば、引数の値が 0 のパラメーターPositionには、Position=1 のパラメーター属性があります。

ParameterSetName 引数

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

注意

コマンドレットまたは関数の場合、パラメーター セットは 32 個に制限されています。

次の例では、パラメーター セットで ComputerComputerName パラメーター、パラメーター セットの UserUserName パラメーター、および両方のパラメーター セットの 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引数のみを指定できます。 1 つのパラメーターが複数のパラメーター セットに表示されることを示すには、 追加の Parameter 属性を追加します。

次の例では、 Summary パラメーターを と User パラメーター セットに明示的にComputer追加します。 Summary パラメーターはパラメーター セットではComputer省略可能で、パラメーター セットではUser必須です。

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
)

パラメーター セットの詳細については、「コマンドレット パラメーター セット」を参照してください。

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
)

注意

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

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

遅延バインド スクリプト ブロックについては、about_Script_Blocks.md を参照してください。

ValueFromRemainingArguments 引数

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

ValueFromRemainingArguments でコレクションを使用すると、渡されたコレクションが 1 つの要素として扱われるという既知の問題があります。

次の例は、この既知の問題を示しています。 Remaining パラメーターには、インデックス 01 つ、インデックス 12 つを含める必要があります。 代わりに、両方の要素が 1 つのエンティティに結合されます。

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory = $true, Position=0)]
         $Value,
         [string[]]
         [Parameter(Position=1, ValueFromRemainingArguments)]
         $Remaining)
     "Found $($Remaining.Count) elements"
     for ($i = 0; $i -lt $Remaining.Count; $i++)
     {
        "${i}: $($Remaining[$i])"
     }
}
Test-Remainder first one,two
Found 1 elements
0: one two

注意

この問題は PowerShell 6.2 で解決されています。

HelpMessage 引数

引数は HelpMessage 、パラメーターまたはその値の簡単な説明を含む文字列を指定します。 PowerShell は、必須パラメーター値がコマンドに指定されていない場合に表示されるプロンプトにこのメッセージを表示します。 この引数は、省略可能なパラメーターには影響しません。

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

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

Alias 属性

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

次の例は、必須の ComputerName パラメーターに CNMachineName のエイリアスを追加するパラメーター宣言を示しています。

Param(
    [Parameter(Mandatory=$true)]
    [Alias("CN","MachineName")]
    [String[]]
    $ComputerName
)

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

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

AllowNull 検証属性

AllowNull 属性を使用すると、必須パラメーターの値を にできます$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 属性は、パラメーターが受け入れるパラメーター値の最小数と最大数を指定します。 関数を呼び出すコマンドのパラメーター値の数がその範囲外にある場合、PowerShell はエラーを生成します。

次のパラメーター宣言では、1 ~ 5 個のパラメーター値を受け取る ComputerName パラメーターを作成します。

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

ValidateLength 検証属性

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

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

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

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

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

ValidatePattern 検証属性

ValidatePattern 属性は、パラメーターまたは変数値と比較される正規表現を指定します。 値が正規表現パターンと一致しない場合、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 属性は、各パラメーターまたは変数値の数値範囲を指定します。 値がその範囲外の場合、PowerShell はエラーを生成します。 次の例では、 Attempts パラメーターの値は 0 から 10 の間である必要があります。

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

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

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

ValidateScript 検証属性

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

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

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

Param(
    [Parameter(Mandatory=$true)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]
    $EventDate
)

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

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

ValidateSet 属性

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

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

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

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

検証は、スクリプト内でも変数が割り当てられるたびに発生します。 たとえば、次の例では実行時にエラーが発生します。

Param(
    [ValidateSet("hello", "world")]
    [String]$Message
)

$Message = "bye"

ValidateNotNull 検証属性

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

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

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

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

ValidateNotNullOrEmpty 検証属性

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

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

動的パラメーター

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

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

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

動的パラメーターは便利ですが、ユーザーが検出するのが困難な場合があるため、必要な場合にのみ使用します。 動的パラメーターを検索するには、ユーザーがプロバイダー パスに存在するか、コマンドレットの ArgumentList パラメーターを Get-Command 使用するか、 の Path パラメーター Get-Helpを使用する必要があります。

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

構文は次のとおりです。

DynamicParam {<statement-list>}

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

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

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

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

function Get-Sample {
  [CmdletBinding()]
  Param([String]$Name, [String]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $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
    }
  }
}

詳細については、「 RuntimeDefinedParameter」を参照してください。

スイッチ パラメーター

スイッチ パラメーターは、パラメーター値のないパラメーターです。 これらは、使用され、効果が 1 つしかない場合にのみ有効です。

たとえば、powershell.exeNoProfile パラメーターは switch パラメーターです。

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

例:

Param([Switch]<ParameterName>)

または、別のメソッドを使用することもできます。

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

スイッチ パラメーターは使いやすく、より難しい構文を持つブール型パラメーターよりも優先されます。

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

-IncludeAll

ブール値パラメーターを使用するには、ユーザーがパラメーターとブール値を入力します。

-IncludeAll:$true

スイッチ パラメーターを作成するときは、パラメーター名を慎重に選択してください。 パラメーター名がパラメーターの効果をユーザーに伝えるようにしてください。 が必要であることを示すフィルターや最大値などのあいまいな用語は避けてください。

ArgumentCompleter 属性

ArgumentCompleter 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 DynamicParameters と同様に、ユーザーがパラメーター名の後に Tab キーを押すと、実行時に使用可能な値が計算されます。

ArgumentCompleter 属性を追加するには、値を決定するスクリプト ブロックを定義する必要があります。 スクリプト ブロックは、次に示す順序で次のパラメーターを受け取る必要があります。 パラメーターの名前は、値が位置指定されるため、重要ではありません。

構文は次のとおりです。

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
        # Perform calculation of tab completed values here.
    })]
)

ArgumentCompleter スクリプト ブロック

スクリプト ブロック パラメーターは、次の値に設定されます。

  • $commandName (位置 0) - このパラメーターは、スクリプト ブロックがタブ補完を提供するコマンドの名前に設定されます。
  • $parameterName (位置 1) - このパラメーターは、タブ補完を必要とする値を持つパラメーターに設定されます。
  • $wordToComplete (位置 2) - このパラメーターは、 ユーザーが Tab キーを押す前に指定した値に設定されます。スクリプト ブロックでは、この値を使用してタブ補完値を決定する必要があります。
  • $commandAst (位置 3) - このパラメーターは、現在の入力行の抽象構文ツリー (AST) に設定されます。 詳細については、「 Ast クラス」を参照してください。
  • $fakeBoundParameter(位置 4) - このパラメーターは、ユーザーが Tab キーを押す$PSBoundParameters前に、 コマンドレットの を含むハッシュテーブルに設定されます。詳細については、「about_Automatic_Variables」を参照してください。

ArgumentCompleter スクリプト ブロックでは、パイプライン (、 などForEach-ObjectWhere-Object) または別の適切なメソッドを使用して値の登録を解除する必要があります。 値の配列を返すと、PowerShell は配列全体を 1 つの タブ補完値として扱います。

次の例では、タブ補完を Value パラメーターに追加します。 が指定されていない $Type 場合は、果物と野菜が返されます。 が $Type 指定されている場合、型の値のみが指定されます。 さらに、オペレーターは -like 、ユーザーが次のコマンドを入力し、 Tab 補完を使用する場合、 Apple のみが返されるようにします。

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

こちらもご覧ください

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute