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 was not recognized as a valid
 DateTime."
At line:13 char:15
+ Get-Date_Func $dateStr
+               ~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func

静的パラメーター

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

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

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

スイッチ パラメーター

スイッチパラメーターは、パラメーター値を受け取らないパラメーターです。 代わりに、ブール値の true または false の値が存在するか欠勤されていることを示しています。そのため、スイッチパラメーターが存在する場合は true の値を持ち、存在しない場合は false の値を持ちます。

たとえば、の Get-ChildItem 再帰 パラメーターはスイッチパラメーターです。

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

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

Param([switch]$AsByteArray)

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

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

-IncludeAll

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

-IncludeAll $true

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

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

  • スイッチパラメーターに既定値を指定することはできません。 常に既定値の false に設定する必要があります。

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

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

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

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

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

    if ($MySwitch) { ... }

    記述する必要はありません。 if ($MySwitch.IsPresent) { ... }

動的パラメーター

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

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

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

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

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

構文は次のとおりです。

dynamicparam {<statement-list>}

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

次の例では、 NamePath という名前の標準パラメーターと、オプションの動的パラメーター ( keycount) を含む関数を示します。 Keycount パラメーターはパラメーターセット内に ByRegistryPath あり、型 Int32 はです。 Keycount パラメーターは、 Path パラメーターの値がで HKLM: 始まっている場合にのみ、関数で Get-Sample 使用できます。これは、レジストリドライブで 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
    }
  }
}

詳細については、 Runtimeのパラメーター の型に関するドキュメントを参照してください。

パラメーターの属性

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

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

各パラメーター宣言には、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)]
)

引数を指定せずに パラメーター 属性を使用する場合、 この属性を 使用する代わりに、属性名の後に続くかっこが必要になります。

Param(
    [Parameter()]
    $ParameterName
)

必須の引数

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

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

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

Position 引数

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

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

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

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

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

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

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

ParameterSetName 引数

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

注意

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

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

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

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

    [Parameter()]
    [switch]
    $Summary
)

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

次の例では、 パラメーター セットと パラメーター セットに 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
)

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

ValueFromPipeline 引数

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

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

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

ValueFromPipelineByPropertyName 引数

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

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

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

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

注意

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

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

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

ValueFromRemainingArguments 引数

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

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

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

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

注意

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

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」 を参照してください

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
)

注意

型コンバーターが string に設定されている場合、AllowNull 属性は機能しません。文字列型は null 値を受け取らないので、 このシナリオでは 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 validation 属性

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

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

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

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

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

ValidateScript validation 属性

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 の値は、チョコレート、Strawberry、またはバニラのいずれかである必要があります。

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

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

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

$Message = "bye"

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

The attribute cannot be added because variable Message with value bye would no
longer be valid.
At line:1 char:1
+ [ValidateSet("hello", "world")][string]$Message = 'bye'
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : MetadataError: (:) [], ValidationMetadataException
    + FullyQualifiedErrorId : ValidateSetFailure

を使用 ValidateSet すると、そのパラメーターの値をタブで拡張することもできます。 詳細については、「 about_Tab_Expansion」を参照してください。

クラスを使用した動的 ValidateSet 値

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

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.

ドライブは、十分な管理 (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 validation 属性

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

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

関連項目