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
)

スイッチ パラメーター

スイッチ パラメーターは、パラメーター値を受け取るパラメーターです。 代わりに、ブール値の true または false 値が存在するか、存在しないかを通じて伝えるので、switch パラメーターが存在する場合は true 値を持ち、存在しない場合は false 値を持ちます。

たとえば、 の Recurse パラメーター Get-ChildItem は switch パラメーターです。

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

たとえば、関数には、データをバイト配列として出力するオプションがあります。

Param([switch]$AsByteArray)

Switch パラメーターは使いやすく、PowerShell の構文があまり自然ではないブール型パラメーターよりも優先されます。

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

-IncludeAll

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

-IncludeAll $true

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

スイッチ パラメーターの設計に関する考慮事項

• スイッチ パラメーターには既定値を指定しないでください。 既定値は常に false である必要があります。

• スイッチ パラメーターは、既定で位置指定パラメーターから除外されます。 他のパラメーターが暗黙的に位置指定されている場合でも、スイッチ パラメーターは指定されません。 これは Parameter 属性でオーバーライド できますが 、ユーザーが混乱します。

• スイッチ パラメーターを設定すると、コマンドが既定の機能からあまり一般的ではない、またはより複雑なモードに移動するように設計する必要があります。 コマンドの最も簡単な動作は、スイッチ パラメーターを使用する必要のない既定の動作です。

• スイッチ パラメーターは必須ではありません。 switch パラメーターを必須にする必要がある唯一のケースは、パラメーター セットを区別するために必要な場合です。

• ブール値からのスイッチを明示的に設定するには、 と を使用 -MySwitch:$boolValue したスプラッティングを使用 $params = @{ MySwitch = $boolValue }します。

• スイッチ パラメーターは 型 SwitchParameterであり、暗黙的にブール型に変換されます。 パラメーター変数は、条件式で直接使用できます。 例:

  if ($MySwitch) { ... }

  書く必要はありません if ($MySwitch.IsPresent) { ... }

動的パラメーター

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

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

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

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

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

構文は次のとおりです。

dynamicparam {<statement-list>}

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

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

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

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [Int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

詳細については、 RuntimeDefinedParameter 型のドキュメントを参照してください。

パラメーターの属性

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

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

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

パラメーター属性

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

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

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

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

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

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

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

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

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)]
    [string[]]
    $ComputerName
)

Position 引数

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

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

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

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

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

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

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

ParameterSetName 引数

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

注意

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

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

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

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

    [Parameter()]
    [switch]
    $Summary
)

各引数には 1 つのParameterSetName値のみを指定でき、各 Parameter 属性には 1 つのParameterSetName引数のみを指定できます。 パラメーターが複数のパラメーター セットに表示されることを示すには、追加の Parameter 属性を追加します。

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

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

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

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]
    $Summary
)

パラメーター セットの詳細については、「 About Parameter Sets」を参照してください。

ValueFromPipeline 引数

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

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

Param(
    [Parameter(Mandatory,
    ValueFromPipeline)]
    [string[]]
    $ComputerName
)

ValueFromPipelineByPropertyName 引数

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

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

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

Param(
    [Parameter(Mandatory,
    ValueFromPipelineByPropertyName)]
    [string[]]
    $ComputerName
)

注意

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

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

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

ValueFromRemainingArguments 引数

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

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

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory, 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,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [string[]]
    $ComputerName
)

Alias 属性

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

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

Param(
    [Parameter(Mandatory)]
    [Alias("CN","MachineName")]
    [string[]]
    $ComputerName
)

SupportsWildcards 属性

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

Param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]
    $Path
)

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

引数補完属性

ArgumentCompletions 属性

ArgumentCompletions 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 ArgumentCompletions 属性は、タブ補完が必要なパラメーターごとに定義する必要があります。 ArgumentCompletions 属性は ValidateSet に似ています。 どちらの属性も、ユーザーがパラメーター名の後に Tab キーを押したときに表示される値の一覧を取得します。 ただし、 ValidateSet とは異なり、値は検証されません。

この属性は、PowerShell 6.0 で導入されました。

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

ArgumentCompleter 属性

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

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

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

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

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

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

注意

検証属性は、パラメーターだけでなく、任意の変数に適用できます。 スクリプト内の任意の変数の検証を定義できます。

AllowNull 検証属性

AllowNull 属性を使用すると、必須パラメーターの値を にできます$null。 次の例では、null 値を持つ可能性があるハッシュテーブル ComputerInfo パラメーターを宣言します。

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

注意

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

AllowEmptyString 検証属性

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

Param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]
    $ComputerName
)

AllowEmptyCollection 検証属性

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

Param(
    [Parameter(Mandatory)]
    [AllowEmptyCollection()]
    [string[]]
    $ComputerName
)

ValidateCount 検証属性

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

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

Param(
    [Parameter(Mandatory)]
    [ValidateCount(1,5)]
    [string[]]
    $ComputerName
)

ValidateLength 検証属性

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

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

Param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]
    $ComputerName
)

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

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

注意

この例では、 の 01 値は単一引用符で囲まれています。 ValidateLength 属性は、引用符で囲まれていないと数値を受け入れません。

ValidatePattern 検証属性

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

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

Param(
    [Parameter(Mandatory)]
    [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 属性は、各パラメーターまたは変数値の数値範囲または ValidateRangeKind 列挙値を指定します。 値がその範囲外の場合、PowerShell はエラーを生成します。

ValidateRangeKind 列挙型では、次の値を使用できます。

• 正 - 0 より大きい数値。
• 負 の値 - 0 未満の数値。
• NonPositive - 0 以下の数値。
• NonNegative - 0 以上の数値。

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

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

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

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

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

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

ValidateScript 検証属性

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

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

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

Param(
    [Parameter(Mandatory)]
    [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)]
    [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"

この例では、実行時に次のエラーが返されます。

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

を使用すると ValidateSet 、そのパラメーターの値のタブ展開も有効になります。 詳細については、「 about_Tab_Expansion」を参照してください。

クラスを使用した動的 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()]
    [ValidateNotNull()]
    $ID
)

ValidateNotNullOrEmpty 検証属性

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

Param(
    [Parameter(Mandatory)]
    [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.

ドライブは、Just Enough Administration (JEA) セッション構成で定義 User できます。 この例では、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

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

ValidateTrustedData 検証属性

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

現時点では、 属性は PowerShell 自体によって内部的に使用され、外部使用を目的としたものではありません。

こちらもご覧ください

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute