12. 属性

  • [アーティクル]

''属性'' オブジェクトでは、定義済みのシステム情報を ''ターゲット要素'' に関連付けます。これは、param ブロックまたはパラメーター (§8.10) にすることができます。 各属性オブジェクトには ''属性型'' があります。

属性によって提供される情報は、''メタデータ'' とも呼ばれます。 メタデータは、コマンドでのデータの処理方法を制御するためにコマンドまたは実行環境を使用するか、コマンド自体の処理または保持方法を制御するために実行時前に外部ツールを使用して調べることができます。

複数の属性を同じターゲット要素に適用することができます。

12.1 属性の指定

ヒント

構文定義での ~opt~ という表記は、その字句エンティティが構文内で省略可能であることを示します。

attribute-list:
    attribute
    attribute-list new-lines~opt~ attribute

attribute:
    [ new-lines~opt~ attribute-name ( attribute-arguments new-lines~opt~ ) new-lines~opt~ ]
    type-literal

attribute-name:
    type-spec

attribute-arguments:
    attribute-argument
    attribute-argument new-lines~opt~ ,
    attribute-arguments

attribute-argument:
    new-lines~opt~ expression
    new-lines~opt~ simple-name
    new-lines~opt~ simple-name = new-lines~opt~ expression

属性は attribute-name と、位置指定および名前付き引数の省略可能なリストで構成されます。 位置指定引数 (ある場合) は名前付き引数の前にあります。 名前付き引数は simple-name と、必要に応じて、その後に続く等号および ''式'' で構成されます。 式が省略されている場合、値 $true が想定されます。

attribute-name は予約済みの属性型 (§12.3) または何らかの実装定義の属性型です。

12.2 属性インスタンス

属性インスタンスは、属性型のオブジェクトです。 インスタンスは実行時の属性を表します。

属性型 A のオブジェクトを作成するには、表記 A() を使用します。 属性は、[A()] のように、そのインスタンスを [] で囲むことで宣言されます。 一部の属性型には、関数やコマンドレットと同様に、位置指定および名前付きパラメーター (§8.14) があります。 たとえば、次のように入力します。

[A(10,IgnoreCase=$true)]

これは、型 A のインスタンスを示しています。引数値が 10 の位置指定パラメーターと、引数値が $true の名前付きパラメーター IgnoreCase を使用して作成されます。

12.3 予約済みの属性

次のセクションで説明する属性は、PowerShell 関数、フィルター、スクリプト、およびコマンドレットの動作を補強または変更するために使用できます。

12.3.1 Alias 属性

この属性は、パラメーターの代替名を指定するために script-parameter で使用されます。 パラメーターには複数のエイリアスが含まれる場合があり、各エイリアス名は、parameter-list 内で一意である必要があります。 1 つの用途として、異なるパラメーター セット内のパラメーターに異なる名前を付けることが考えられます (ParameterSetName を参照)。

属性引数の型は string[] です。

次の param ブロックを持つ関数呼び出し Test1 があるとします。これは次のように呼び出されます。

param (
    [Parameter(Mandatory = $true)]
    [Alias("CN")]
    [Alias("name", "system")]
    [string[]] $ComputerName
)

Test1 "Mars", "Saturn"                # pass argument by position
Test1 -ComputerName "Mars", "Saturn"  # pass argument by name
Test1 -CN "Mars", "Saturn"            # pass argument using first alias
Test1 -name "Mars", "Saturn"          # pass argument using second alias
Test1 -sys "Mars", "Saturn"           # pass argument using third alias

次の param ブロックを持つ関数呼び出し Test2 があるとします。これは次のように呼び出されます。

param (
    [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
    [Alias('PSPath')]
    [string] $LiteralPath
)

Get-ChildItem "E:\*.txt" | Test2 -LiteralPath { $_ ; "`n`t";
    $_.FullName + ".bak" }
Get-ChildItem "E:\*.txt" | Test2

コマンドレット Get-ChildItem (エイリアス Dir) では、PSPath という string 型の新しい NoteProperty を返すオブジェクトに追加します。

12.3.2 AllowEmptyCollection 属性

この属性は、必須パラメーターの引数として空のコレクションを許可するために、script-parameter で使用されます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [parameter(Mandatory = $true)]
    [AllowEmptyCollection()]
    [string[]] $ComputerName
)

Test "Red", "Green" # $computerName has Length 2
Test "Red" # $computerName has Length 1
Test -comp @() # $computerName has Length 0

12.3.3 AllowEmptyString 属性

この属性は、必須パラメーターの引数として空の文字列を許可するために、script-parameter で使用されます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [parameter(Mandatory = $true)]
    [AllowEmptyString()]
    [string] $ComputerName
)

Test "Red" # $computerName is "Red"
Test "" # empty string is permitted
Test -comp "" # empty string is permitted

12.3.4 AllowNull 属性

この属性は、暗黙的な変換が使用できない必須パラメーターの引数として $null を許可するために、script-parameter で使用されます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [parameter(Mandatory = $true)]
    [AllowNull()]
    [int[]] $Values
)

Test 10, 20, 30     # $values has Length 3, values 10, 20, 30
Test 10, $null, 30  # $values has Length 3, values 10, 0, 30
Test -val $null     # $values has value $null

上記の 2 番目のケースでは、この属性が不要であることに注意してください。つまり、$null から int への暗黙的な変換が既に存在します。

12.3.5 CmdletBinding 属性

この属性は、関数がコマンドレットのように動作することを示すために、関数の param-block の attribute-list で使用されます。 具体的には、begin、process、および end 名前付きブロック (§8.10.7) を使用して、関数で $PsCmdlet 変数を介して多数のメソッドとプロパティにアクセスできるようにします。

この属性が存在する場合、位置指定パラメーターと一致しない位置引数では、パラメーター バインドが失敗し、$args が定義されません (この属性がない場合、$args では一致しない位置引数の値を取ります)。

パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
SupportsShouldProcess (名前付き)

型: bool; 既定値: $false

関数でシステムに変更を行う前にユーザーにフィードバックを求めるために使用される、ShouldProcess メソッドの呼び出しをその関数でサポートするかどうかを指定します。 値 $true は、そうであることを示します。 値 $false は、そうでないことを示します。
ConfirmImpact (名前付き)

型: string; 既定値: "Medium"

実行されるアクションの影響レベルを指定します。 ShouldProcess メソッドの呼び出しでは、ConfirmImpact 引数が ConfirmPreference ユーザー設定変数の値以上である場合にのみ、確認プロンプトが表示されます。

この引数で使用可能な値は次のとおりです。

None: 確認のためのすべての要求を抑制します。

Low: データが失われるリスクが低いアクションが実行されます。

Medium: データが失われるリスクが中程度のアクションが実行されます。

High: データが失われるリスクが高いアクションが実行されます。

影響レベルが同じまたはそれより高いコマンドレットでのみ、操作の実行前に確認を要求できるように、$ConfirmPreference の値を設定できます。 たとえば、$ConfirmPreference が Medium に設定されている場合、影響レベルが中程度または高いコマンドレットで確認を要求できます。 影響レベルが低いコマンドレットからの要求は抑制されます。
DefaultParameterSetName (名前付き)

型: string; 既定値: "__AllParameterSets"

引数から判断できない場合に使用するパラメーター セットを指定します。 Parameter 属性 ([§12.3.7][§12.3.7]) の名前付き引数 ParameterSetName を参照してください。
PositionalBinding (名前付き)

型: bool; 既定値: $true

位置指定バインドがサポートされるかどうかを指定します。 Parameter 属性 ([§12.3.7][§12.3.7]) の名前付き引数 Position または名前付き引数 ParameterSetName に対して、パラメーターで既定以外の値が指定された場合、この引数の値は無視されます。 それ以外の場合、引数が $false であれば、パラメーターは位置指定ではないか、パラメーターに、その指定された順序に基づいて位置が割り当てられます。

この属性を使用するためのフレームワークの例を以下に示します。

[CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = "Low")]
param ( ... )

begin { ... }
Get-process { ... }
end { ... }

12.3.6 OutputType 属性

この属性は、返される型を指定するために、param-block の attribute-list で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
Type (位置 0)

型: string[] またはリテラル型の配列

返される値の型のリスト。
ParameterSetName (名前付き)

型: string[]

Type パラメーターの対応する要素によって示される型を返すパラメーター セットを指定します。

この属性の使用例をいくつか以下に示します。

[OutputType([int])] param ( ... )
[OutputType("double")] param ( ... )
[OutputType("string","string")] param ( ... )

12.3.7 Parameter 属性

この属性は、script-parameter で使用されます。 パラメーターの特性を定義するには、次の名前付き引数を使用します。

パラメーター 目的
HelpMessage (名前付き)

Type: 文字列

この引数では、パラメーターの簡単な説明を含めることを目的としたメッセージを指定します。 このメッセージは、関数またはコマンドレットを実行しても、HelpMessage を含む必須パラメーターに対応する引数がない場合に、実装定義の方法で使用されます。

次の例は、パラメーターの説明を提供するパラメーター宣言を示しています。

param ( [Parameter(Mandatory = $true,
HelpMessage = "コンピューター名の配列。")]
[string[]] $ComputerName )

Windows PowerShell: 必須パラメーターが指定されていない場合、ランタイムではユーザーにパラメーター値の入力を求めるメッセージが表示されます。 プロンプト ダイアログ ボックスには、HelpMessage テキストが含まれます。
Mandatory (名前付き)

型: bool; 既定値: $false

この引数では、指定されたパラメーター セット内でパラメーターが必要かどうかを指定します (下記の ParameterSetName 引数を参照)。 値 $true は、そうであることを示します。 値 $false は、そうでないことを示します。

param ( [Parameter(Mandatory = $true)]
[string[]] $ComputerName )

Windows PowerShell: 必須パラメーターが指定されていない場合、ランタイムではユーザーにパラメーター値の入力を求めるメッセージが表示されます。 プロンプト ダイアログ ボックスには、HelpMessage テキスト (ある場合) が含まれます。
ParameterSetName (名前付き)

型: string; 既定値: "__AllParameterSets"

シナリオごとに異なるアクションを実行できる 1 つの関数またはコマンドレットを記述できます。 これは、実行するアクションに応じて、さまざまなパラメーター グループを公開することで行います。 このようなパラメーター グループは ''パラメーター セット'' と呼ばれます。

引数 ParameterSetName では、パラメーターが属するパラメーター セットを指定します。 この動作は、各パラメーター セットに、他のパラメーター セットのメンバーではない一意のパラメーターが 1 つ必要であることを意味します。

複数のパラメーター セットに属するパラメーターの場合は、パラメーター セットごとに Parameter 属性を追加します。 これにより、パラメーター セットごとに異なる方法でパラメーターを定義できるようになります。

複数の位置指定パラメーターを含むパラメーター セットでは、パラメーターごとに一意の位置を定義する必要があります。 2 つの位置指定パラメーターで同じ位置を指定することはできません。

パラメーターにパラメーター セットが指定されていない場合、パラメーターはすべてのパラメーター セットに属します。

複数のパラメーター セットが定義されている場合は、既定のパラメーター セットを指定するために、CmdletBinding 属性 ([§12.3.5][§12.3.5]) の名前付き引数 DefaultParameterSetName が使用されます。 ランタイムでは、コマンドによって指定された情報に基づいて使用するパラメーター セットを判断できない場合に既定のパラメーター セットを使用するか、既定のパラメーター セットが指定されていない場合は例外を発生させます。

次の例は、2 つの異なるパラメーター セットに属する 2 つのパラメーターと、両方のセットに属する 3 番目のパラメーターのパラメーター宣言を含む Test 関数を示しています。

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

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

[Parameter(Mandatory = $true,
ParameterSetName = "Computer")]
[Parameter(ParameterSetName = "User")]
[int] $SharedParam = 5 )

if ($PsCmdlet.ParameterSetName -eq "Computer")
{
# "Computer" パラメーターセットを処理します
}

elseif ($PsCmdlet.ParameterSetName -eq "User")
{
# "User" パラメーター セットを処理します
}
…
}

Test -ComputerName "Mars","Venus" -SharedParam 10
Test -UserName "Mary","Jack"
Test -UserName "Mary","Jack" -SharedParam 20
Position (名前付き)

型: int

この引数では、引数リスト内のパラメーターの位置を指定します。 この引数が指定されていない場合、パラメーターの設定時にパラメーター名またはそのエイリアスを明示的に指定する必要があります。 関数のどのパラメーターにも位置がない場合、位置は受け取られた順序に基づいて各パラメーターに割り当てられます。

次の例は、関数の呼び出し時に最初の引数として値を指定する必要があるパラメーターの宣言を示しています。

param ( [Parameter(Position = 0)]
[string[]] $ComputerName )
ValueFromPipeline (名前付き)

型: bool; 既定値: $false

この引数では、パラメーターでパイプライン オブジェクトからの入力を受け入れるかどうかを指定します。 値 $true は、そうであることを示します。 値 $false は、そうでないことを示します。

関数またはコマンドレットで、オブジェクトのプロパティだけでなく、完全なオブジェクトにアクセスする場合は $true を指定します。

パラメーター セット内の 1 つのパラメーターのみで、ValueFromPipeline を $true として宣言できます。

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

param ( [Parameter(Mandatory = $true,
ValueFromPipeline=$true)]
[string[]] $ComputerName )

このパラメーターと Alias 属性を組み合わせて使用する例については、[§12.3.1][§12.3.1] を参照してください。

ValueFromPipelineByPropertyName (名前付き)

型: bool; 既定値: $false

この引数では、パラメーターで、このパラメーターと同じ名前または同じエイリアスを持つパイプライン オブジェクトのプロパティから値を取得するかどうかを指定します。 値 $true は、そうであることを示します。 値 $false は、そうでないことを示します。

次の条件に当てはまる場合は、$true を指定します: パラメーターでパイプ処理されたオブジェクトのプロパティにアクセスし、プロパティの名前がパラメーターと同じか、プロパティのエイリアスがパラメーターと同じである。

ValueFromPipelineByPropertyName が $true に設定されているパラメーターには、ValueFromPipeline が $true に設定されている同じセット内にパラメーターを含める必要はありません。

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

param ( [parameter(Mandatory = $true,
ValueFromPipelineByPropertyName = $true)]
[string[]] $ComputerName )

パラメーター セット内の複数のパラメーターで、ValueFromPipelineByPropertyName を $true として定義できます。 1 つの入力オブジェクトを複数のパラメーターにバインドすることはできませんが、その入力オブジェクト内の異なるプロパティを異なるパラメーターにバインドすることはできます。

入力オブジェクトのプロパティとパラメーターをバインドする場合、ランタイム環境ではまず、パラメーターと同じ名前のプロパティを探します。 このようなプロパティが存在しない場合、ランタイム環境では、プロパティが存在する最初のエイリアスを選択し、そのパラメーターのエイリアスを宣言順に探します。

function Process-Date
{
param(
[Parameter(ValueFromPipelineByPropertyName=$true)]
[int]$Year,

[Parameter(ValueFromPipelineByPropertyName=$true)]
[int]$Month,

[Parameter(ValueFromPipelineByPropertyName=$true)]
[int]$Day
)

process { … }
}

Get-Date | Process-Date
ValueFromRemainingArguments (名前付き)

型: bool; 既定値: $false

この引数では、関数のパラメーターにバインドされていない残りのすべての引数をパラメーターで受け入れるかどうかを指定します。 値 $true は、そうであることを示します。 値 $false は、そうでないことを示します。

次の例は、Test 関数に渡される入力オブジェクトの残りのすべての引数を受け入れるパラメーター $others を示しています。

param ( [parameter(Mandatory = $true)][int] $p1,
[parameter(Mandatory = $true)][int] $p2,
[parameter(ValueFromRemainingArguments = $true)]
[string[]] $others )

Test 10 20 # $others の Length は 0 です
Test 10 20 30 40 # $others の Length は 2、値は 30, 40 です

実装では他の属性も定義される場合があります。

次の属性も提供されます。

  • HelpMessageBaseName: リソース識別子が存在する場所を指定します。 たとえば、このパラメーターでは、ローカライズされる Help メッセージを含むリソース アセンブリを指定できます。
  • HelpMessageResourceId: Help メッセージのリソース識別子を指定します。

12.3.8 PSDefaultValue 属性

この属性は、パラメーターに関する追加情報を提供するために、script-parameter で使用されます。 属性は実装定義の方法で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
Help (名前付き)

Type: 文字列

この引数では、パラメーターの既定値の簡単な説明を含めることを目的としたメッセージを指定します。 このメッセージは実装定義の方法で使用されます。

Windows PowerShell: メッセージは、[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) コマンドレットによって表示されるヘルプ トピックのパラメーターの説明の一部として使用されます。
Value (名前付き)

型: object

この引数では、パラメーターの既定値にすることを目的とした値を指定します。 この値は実装定義の方法で使用されます。

Windows PowerShell: この値は、Help プロパティが指定されていない場合に、[Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) コマンドレットによって表示されるヘルプ トピックのパラメーターの説明の一部として使用されます。

12.3.9 SupportsWildcards 属性

この属性は、パラメーターに関する追加情報を提供するために、script-parameter で使用されます。 属性は実装定義の方法で使用されます。

この属性は、Get-Help コマンドレットによって表示されるヘルプ トピックのパラメーターの説明の一部として使用されます。

12.3.10 ValidateCount 属性

この属性は、パラメーターで受け入れ可能な引数値の最小および最大数を指定するために、script-parameter で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
MinLength (位置 0)

型: int

この引数では、許可される引数値の最小数を指定します。
MaxLength (位置 1)

型: int

この引数では、許可される引数値の最大数を指定します。

この属性がない場合、パラメーターの対応する引数値リストは任意の長さにすることができます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [ValidateCount(2, 5)]
    [int[]] $Values
)

Temp 10, 20, 30
Temp 10                         # too few argument values
Temp 10, 20, 30, 40, 50, 60     # too many argument values

[ValidateCount(3, 4)]$Array = 1..3
$Array = 10                     # too few argument values
$Array = 1..100                 # too many argument values

12.3.11 ValidateLength 属性

この属性は、パラメーターの引数の最小および最大長を指定するために、script-parameter または ''変数'' で使用されます。これは string 型である必要があります。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
MinLength (位置 0)

型: int

この引数では、許可される最小文字数を指定します。
MaxLength (位置 1)

型: int

この引数では、許可される最大文字数を指定します。

この属性がない場合、パラメーターの対応する引数は任意の長さにすることができます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param ( [parameter(Mandatory = $true)]
[ValidateLength(3,6)]
[string[]] $ComputerName )

Test "Thor","Mars"     # length is ok
Test "Io","Mars"       # "Io" is too short
Test "Thor","Jupiter"  # "Jupiter" is too long

12.3.12 ValidateNotNull 属性

この属性は、パラメーターの引数を $null にしたり、null 値要素を含むコレクションにしたりできないことを指定するために、script-parameter または ''変数'' で使用されます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [ValidateNotNull()]
    [string[]] $Names
)

Test "Jack", "Jill"     # ok
Test "Jane", $null      # $null array element value not allowed
Test $null              # null array not allowed

[ValidateNotNull()]$Name = "Jack" # ok
$Name = $null           # null value not allowed

12.3.13 ValidateNotNullOrEmpty 属性

この属性は、パラメーターを $null にしたり、$null 値要素または空の文字列要素を含むコレクションにしたりできないことを指定するために、script-parameter または ''変数'' で使用されます。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [ValidateNotNullOrEmpty()]
    [string[]] $Names
)

Test "Jack", "Jill"    # ok
Test "Mary", ""        # empty string not allowed
Test "Jane", $null     # $null array element value not allowed
Test $null             # null array not allowed
Test @()               # empty array not allowed

[ValidateNotNullOrEmpty()]$Name = "Jack" # ok
$Name = ""             # empty string not allowed
$Name = $null          # null value not allowed

12.3.14 ValidatePattern 属性

この属性は、パラメーターの引数のパターンを照合する正規表現を指定するために、script-parameter または ''変数'' で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
RegexString (位置 0)

型: String

パラメーターの引数を検証するために使用される正規表現
Options (名前付き)

型: Regular-Expression-Option

許可される値については、[§4.2.6.4][§4.2.6.4] を参照してください。

引数がコレクションである場合、コレクション内の各要素がパターンと一致する必要があります。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [ValidatePattern('\^[A-Z][1-5][0-9]$')]
    [string] $Code,

    [ValidatePattern('\^(0x|0X)([A-F]|[a-f]|[0-9])([A-F]|[a-f]|[0-9])$')]
    [string] $HexNum,

    [ValidatePattern('\^[+|-]?[1-9]$')]
    [int] $Minimum
)

Test -c A12 # matches pattern
Test -c A63 # does not match pattern

Test -h 0x4f # matches pattern
Test -h "0XB2" # matches pattern
Test -h 0xK3 # does not match pattern

Test -m -4 # matches pattern
Test -m "+7" # matches pattern
Test -m -12 # matches pattern, but is too long

[ValidatePattern('\^[a-z][a-z0-9]\*$')]$ident = "abc"
$ident = "123" # does not match pattern

12.3.15 ValidateRange 属性

この属性は、パラメーターの引数の最小および最大値を指定するために、script-parameter または ''変数'' で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
MinRange (位置 0)

型: object

この引数では、許可される最小値を指定します。
MaxRange (位置 1)

型: object

この引数では、許可される最大値を指定します。

この属性がない場合、範囲の制限はありません。

次の param ブロックを持つ関数呼び出し Test1 があるとします。これは次のように呼び出されます。

param (
    [parameter(Mandatory = $true)]
    [ValidateRange(1, 10)]
    [int] $StartValue
)

Test1 2
Test1 -st 7
Test1 -3 # value is too small
Test1 12 # value is too large

次の param ブロックを持つ関数呼び出し Test2 があるとします。これは、次のように呼び出します。

param (
    [parameter(Mandatory = $true)]
    [ValidateRange("b", "f")]
    [string] $Name
)

Test2 "Bravo" # ok
Test2 "Alpha" # value compares less than the minimum
Test2 "Hotel" # value compares greater than the maximum

次の param ブロックを持つ関数呼び出し Test3 があるとします。これは次のように呼び出されます。

param (
    [parameter(Mandatory = $true)]
    [ValidateRange(0.002, 0.003)]
    [double] $Distance
)

Test3 0.002
Test3 0.0019    # value is too small
Test3 "0.005"   # value is too large

[ValidateRange(13, 19)]$teenager = 15
$teenager = 20  # value is too large

12.3.16 ValidateScript 属性

この属性は、パラメーターの引数の検証に使用されるスクリプトを指定するために、script-parameter または ''変数'' で使用されます。

位置 1 の引数は 、script-block-expression です。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param (
    [Parameter(Mandatory = $true)]
    [ValidateScript( { ($_ -ge 1 -and $_ -le 3) -or ($_ -ge 20) })]
    [int] $Count
)

Test 2 # ok, valid value
Test 25 # ok, valid value
Test 5 # invalid value
Test 0 # invalid value

[ValidateScript({$_.Length --gt 7})]$password = "password" # ok
$password = "abc123" # invalid value

12.3.17 ValidateSet 属性

この属性は、パラメーターの引数に有効な値のセットを指定するために、script-parameter または ''変数'' で使用されます。 パラメーターの特性を定義するには、次の引数を使用します。

パラメーター名 目的
ValidValues (位置 0)

型: string[]

有効な値のセット。
IgnoreCase (名前付き)

型: bool; 既定値: $true

string 型のパラメーターで、大文字と小文字の区別を無視する必要があるかどうかを指定します。

パラメーターに array 型がある場合は、対応する引数配列のすべての要素が、設定された値の要素と一致する必要があります。

次の param ブロックを持つ関数呼び出し Test があるとします。これは次のように呼び出されます。

param ( [ValidateSet("Red", "Green", "Blue")]
    [string] $Color,

    [ValidateSet("up", "down", "left", "right", IgnoreCase =
        $false)]
    [string] $Direction

)

Test -col "RED"    # case is ignored, is a member of the set
Test -col "white"  # case is ignored, is not a member of the set

Test -dir "up"     # case is not ignored, is a member of the set
Test -dir "Up"     # case is not ignored, is not a member of the set

[ValidateSet(("Red", "Green", "Blue")]$color = "RED" # ok, case is ignored
$color = "Purple"  # case is ignored, is not a member of the set