about_Functions_Advanced_Parameters

簡単な説明

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

長い説明

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

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

PowerShell 3.0 から、スプラッティング を 使用してコマンドの @Args パラメーターを表す機能を使用できます。 スプラッティングは、単純関数と高度な関数で有効です。 詳細については、「about_Functions とabout_Splatting」を参照してください

パラメーター値の型変換

別の型を必要とするパラメーターに引数として文字列を指定すると、PowerShell は文字列をパラメーターターゲット型に暗黙的に変換します。 高度な関数は、パラメーター値のカルチャインバリアント解析を実行します。

これに対し、カルチャに依存する変換は、コンパイル済みコマンドレットのパラメーター バインド中に実行されます。

この例では、パラメーターを受け取るコマンドレットとスクリプト関数を作成 [datetime] します。 現在のカルチャは、ドイツ語の設定を使用するために変更されます。 ドイツ語形式の日付が パラメーターに渡されます。

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr
Dienstag, 19. Juni 2018 00:00:00

上に示すように、コマンドレットはカルチャを区別する解析を使用して文字列を変換します。

# Define an equivalent function.
function Get-Date_Func {
  param(
    [DateTime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

高度な関数では、カルチャインバリアント解析が使用され、次のエラーが発生します。

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error: "String
'19-06-2018' was not recognized as a valid DateTime."

静的パラメーター

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

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

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

パラメーターの属性

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

すべての属性は省略できます。 ただし、この属性を省略 した場合 、高度な関数として認識されるようにするには、関数に パラメーター 属性を含める必要があります。

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

パラメーター属性

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

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

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

パラメーター 属性、引数、および引数値を宣言するには、次の構文を使用します。 引数とその値を囲むかっこは、余分なスペースを含まない パラメーター の後に指定する必要があります。

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

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

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

Parameter 属性から 省略した場合、 parameter 属性のブール型引数の既定値は False になります。 引数の値をに設定し $true ます。または、引数を名前で一覧表示するだけです。 たとえば、次の パラメーター 属性は同等です。

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

# Boolean arguments can be defined using this shorthand syntax

Param(
    [Parameter(Mandatory)]
)

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

Param(
    [Parameter()]
    $ParameterName
)

必須の引数

引数 Mandatory は、 パラメーターが必須かどうかを示します。 この引数を指定しない場合、 パラメーターは省略可能です。

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

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

Position 引数

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

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

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

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

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

次の例では、 ComputerName パラメーターを宣言しています。 この例では、 Position 値が 0 の引数を使用しています。 結果として、コマンドからを省略した場合、 -ComputerName その値は、コマンドの最初のパラメーター値または無名のパラメーター値である必要があります。

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

ParameterSetName 引数

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

注意

コマンドレットまたは関数の場合、32パラメーターセットの制限があります。

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

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

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

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

各引数に指定できる値は1つだけで ParameterSetNameParameterSetNameパラメーター 属性には1つの引数のみを指定できます。 パラメーターが複数のパラメーターセットに含まれていることを示すには、 パラメーター属性を追加し ます。

次の例では、およびパラメーターセットに Summary パラメーターを明示的に追加し Computer User ます。 パラメーターセットでは 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 Value by PropertyName スクリプト ブロックを使用できます。

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

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

ValueFromRemainingArguments 引数

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

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

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 2 elements
0: one
1: two

注意

PowerShell 6.2 より前では 、ValueFromRemainingArguments コレクションは、インデックス 0 の下の単一エンティティ として結合されました

HelpMessage 引数

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

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

関数に他の コメントベースのヘルプ 構文 (など) がない場合は、 .SYNOPSIS このメッセージも出力に表示さ Get-Help れます。

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

Alias 属性

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

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

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

SupportsWildcards 属性

SupportsWildcards 属性は、パラメーターがワイルドカード値を受け入れることを示すために使用されます。 次の例は、ワイルドカード値をサポートする必須の パス パラメーターのパラメーター宣言を示しています。

Param(
    [Parameter(Mandatory=$true)]
    [SupportsWildcards()]
    [String[]]
    $Path
)

この属性を使用しても、ワイルドカードのサポートは自動的に有効になりません。 コマンドレットの開発者は、ワイルドカード入力を処理するコードを実装する必要があります。 サポートされているワイルドカードは、基になる API または PowerShell プロバイダーによって異なります。 詳細については、「 about_Wildcards」を参照してください。

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

検証属性は、ユーザーが高度な関数を呼び出したときに送信されるパラメーター値をテストするように PowerShell に指示します。 パラメーター値がテストに失敗した場合は、エラーが生成され、関数は呼び出されません。 パラメーターの検証は、指定された入力にのみ適用され、既定値のようなその他の値は検証されません。

また、検証属性を使用して、ユーザーが変数に指定できる値を制限することもできます。 検証属性と共に型コンバーターを使用する場合は、属性の前に型コンバーターを定義する必要があります。

[int32][AllowNull()] $number = 7

AllowNull 検証属性

Allownull 属性では、必須パラメーターの値をにすることができ $null ます。 次の例では、 null 値を持つことができる Hashtable computerinfo パラメーターを宣言しています。

Param(
    [Parameter(Mandatory=$true)]
    [AllowNull()]
    [hashtable]
    $ComputerInfo
)

注意

型コンバーターが string に設定されている場合、AllowNull 属性は機能しません。文字列型は null 値を受け取らないので、 このシナリオでは AllowEmptyString 属性を使用できます。

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
)

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

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

注意

この例では、 の値 01 が単一引用符で囲まれています。 ValidateLength 属性 は、引用符で囲まれずに数値を受け入れる必要があります。

ValidatePattern 検証属性

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

次の例では、パラメーター値に4桁の数字を含める必要があり、各桁には 0 ~ 9 の数値を指定する必要があります。

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

次の例では、変数の値は4桁の数字にする $number 必要があり、各桁には 0 ~ 9 の数値を指定する必要があります。

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

ValidateRange validation 属性

ValidateRange 属性は、各パラメーターまたは変数値の数値範囲または Validaterangekind 列挙値を指定します。 値が範囲外の場合、PowerShell はエラーを生成します。

Validaterangekind 列挙型では、次の値が許可されます。

  • -0 より大きい数値。
  • -0 未満の数値。
  • 非正 -0 以下の数値。
  • でない-0 以上の数値。

次の例では、 Attempts パラメーターの値を0から10までの範囲で指定する必要があります。

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

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

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

次の例では、変数の値 $number が0より大きい必要があります。

[Int32][ValidateRange("Positive")]$number = 1

ValidateScript validation 属性

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

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

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

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

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

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

注意

ValidateScript を使用する場合 は、 パラメーター $null に値を渡す必要があります。 null 値 ValidateScript を渡した場合、引数を検証できません。

ValidateSet 属性

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

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

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

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

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

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

$Message = "bye"

動的 validateSet 値

クラスを使用すると 実行時に ValidateSet の 値を動的に 生成できます。 次の例では、変数の有効な値は、使用可能なサウンド ファイルの 3 つのファイルシステム パスをチェックする SoundNames という名前のクラスを使用 $Sound して生成されます。

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [String[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [String[]] $SoundNames
    }
}

クラス [SoundNames] は、次のように動的 ValidateSet 値 として実装されます。

Param(
    [ValidateSet([SoundNames])]
    [String]$Sound
)

注意

クラス IValidateSetValuesGenerator は PowerShell 6.0 で導入されました

ValidateNotNull 検証属性

ValidateNotNull 属性 は、パラメーター値を にすることはできません $null 。 パラメーター値が の場合、PowerShell によってエラーが生成されます $null

ValidateNotNull 属性は、 パラメーターが省略可能で、型が未定義の場合、またはオブジェクト のような null 値を暗黙的に変換できない型コンバーターがある場合に使用するように設計 されています文字列 などの null 値を暗黙的に変換する型を指定した場合、 validatenotnull 属性を使用していても null 値は空の文字列に変換されます。 このシナリオでは、 Validatenotnullorempty を使用します。

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

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

ValidateNotNullOrEmpty 検証属性

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

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

ValidateDrive 検証属性

Validatedrive 属性は、パラメーター値がパスを表す必要があることを指定します。これは、許可されるドライブのみを指します。 パラメーター値が許可されている以外のドライブを参照している場合、PowerShell はエラーを生成します。 ドライブ自体を除き、パスの存在は検証されません。

相対パスを使用する場合は、現在のドライブがドライブの一覧に含まれている必要があります。

Param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [String]$Path
)

ValidateUserDrive 検証属性

Validateuserdrive 属性は、パラメーター値がドライブを参照するパスを表す必要があることを指定し User ます。 パスが別のドライブを参照している場合は、PowerShell によってエラーが生成されます。 検証属性は、パスのドライブ部分が存在するかどうかのみをテストします。

相対パスを使用する場合は、現在のドライブがである必要があり User ます。

function Test-UserDrivePath{
    [OutputType([bool])]
    Param(
      [Parameter(Mandatory=, Position=0)][ValidateUserDrive()][String]$Path
      )
    $True
}

Test-UserDrivePath -Path C:\
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

ドライブは、 User 十分な管理 (JEA) セッション構成でのみ定義できます。 この例では、User: ドライブを作成します。

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'
True

ValidateTrustedData validation 属性

この属性は、PowerShell 6.1.1 で追加されました。

現時点では、属性は PowerShell 自体によって内部的に使用され、外部での使用は意図されません。

動的パラメーター

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

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

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

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

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

構文は次のとおりです。

DynamicParam {<statement-list>}

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

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

コマンドを使用して New-Object 、System.Management.Automation.ParameterAttribute オブジェクトを作成し、必須位置**、ValueFromPipeline、** そのパラメーター セットなどのパラメーターの属性を表します。

次の例は、Name と Path という名前の標準パラメーターと、DP1 という名前の省略可能な動的パラメーターを持つサンプル関数 を示していますDP1 パラメーター はパラメーター セット PSet1 内に含み、 型は です Int32Sjc-dp1 パラメーターは、 Get-Sample Path パラメーターの値がで始まっている場合にのみ、関数で使用でき 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
    }
  }
}

詳細については、「 Runtimeのパラメーター」を参照してください。

スイッチ パラメーター

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

たとえば、 powershell.exenoprofile パラメーターはスイッチパラメーターです。

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

以下に例を示します。

Param([Switch]<ParameterName>)

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

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

スイッチパラメーターは簡単に使用でき、より複雑な構文を持つブール型パラメーターよりも優先されます。

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

-IncludeAll

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

-IncludeAll:$true

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

ArgumentCompleter 属性

ArgumentCompleter 属性を使用すると、特定のパラメーターにタブ補完の値を追加できます。 タブ補完が必要な各パラメーターに対して、 ArgumentCompleter 属性を定義する必要があります。 Dynamicparameters と同様に、使用可能な値は、ユーザーがパラメーター名の後に tab キーを押したときに実行時に計算されます。

ArgumentCompleter 属性を追加するには、値を決定するスクリプトブロックを定義する必要があります。 スクリプトブロックは、次のパラメーターを以下の順序で指定する必要があります。 パラメーターの名前は、値が位置に指定されている場合には問題になりません。

構文は次のとおりです。

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

ArgumentCompleter スクリプト ブロック

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

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

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

次の例では、タブ補完を Value パラメーター に追加 します。 Value パラメーター のみを指定 した場合は、Value に指定できるすべての値または引数 表示されます。 Type パラメーター を指定 すると 、Value パラメーターには、その型に指定できる値だけが表示されます。

さらに、 演算子を使用すると、ユーザーが次のコマンドを入力し、Tab 補完を使用すると -like 、Apple だけが返されます。

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory=$true)]
        [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