about_Functions_Advanced_Parameters
簡単な説明
高度な関数にパラメーターを追加する方法について説明します。
長い説明
記述する高度な関数にパラメーターを追加し、パラメーター属性と引数を使用して、関数ユーザーがパラメーターと共に送信するパラメーター値を制限できます。
関数に追加するパラメーターは、PowerShell がすべてのコマンドレットと高度な関数に自動的に追加する共通パラメーターに加えて、ユーザーが使用できます。 PowerShell の共通パラメーターの詳細については、「 about_CommonParameters」を参照してください。
PowerShell 3.0 以降では、 で @Args スプラッティングを使用して、コマンドのパラメーターを表すことができます。 Splatting は、シンプルで高度な機能で有効です。 詳細については、「 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 値を持つよう、ブール値の true または false の値をその有無を通じて伝えます。
たとえば、 の Recurse パラメーター Get-ChildItem は switch パラメーターです。
関数に switch パラメーターを作成するには、パラメーター定義で 型を指定 switch します。
たとえば、関数には、バイト配列としてデータを出力するオプションがあります。
param([switch]$AsByteArray)
スイッチ パラメーターは使いやすく、PowerShell の構文があまり自然ではないブール型パラメーターよりも優先されます。
たとえば、switch パラメーターを使用する場合、ユーザーは コマンドに パラメーターを入力します。
-IncludeAll
ブール値パラメーターを使用するには、パラメーターとブール値を入力します。
-IncludeAll $true
スイッチ パラメーターを作成するときは、パラメーター名を慎重に選択してください。 パラメーター名がパラメーターの効果をユーザーに伝えるようにしてください。 フィルターや最大値など、値が必要であることを意味するあいまいな用語は避けてください。
スイッチ パラメーターの設計に関する考慮事項
スイッチ パラメーターには既定値を指定しないでください。 既定値は常に false である必要があります。
スイッチ パラメーターは、既定では位置指定パラメーターから除外されます。 他のパラメーターが暗黙的に位置指定されている場合でも、スイッチ パラメーターは配置されません。 Parameter 属性ではこれをオーバーライド できますが 、ユーザーが混乱します。
スイッチ パラメーターを設定すると、コマンドが既定の動作から、あまり一般的ではない、または複雑なモードに移動するように設計する必要があります。 コマンドの最も単純な動作は、スイッチ パラメーターの使用を必要としない既定の動作です。
スイッチ パラメーターは必須にしないでください。 switch パラメーターを必須にする必要がある唯一のケースは、パラメーター セットを区別する必要がある場合です。
ブール値からの切り替えを明示的に設定するには、 と を使用
-MySwitch:$boolValueしたスプラッティングを使用$params = @{ MySwitch = $boolValue }します。スイッチ パラメーターの型
SwitchParameterは であり、暗黙的にブール型に変換されます。 パラメーター変数は、条件式で直接使用できます。 例:if ($MySwitch) { ... }書く必要はありません
if ($MySwitch.IsPresent) { ... }
動的パラメーター
動的パラメーターは、特定の条件下でのみ使用できるコマンドレット、関数、またはスクリプトのパラメーターです。
たとえば、いくつかのプロバイダー コマンドレットには、プロバイダー ドライブまたはプロバイダー ドライブの特定のパスでコマンドレットが使用されている場合にのみ使用できるパラメーターがあります。 たとえば、Encoding パラメーターは、ファイル システム ドライブでAdd-ContentGet-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)]
$ParameterName
)
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引数のみを指定できます。 複数のパラメーター セットにパラメーターを含めるには 、パラメーター属性 を追加します。
次の例では、 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
)
次の引数を使用して関数の実装を検討します。
function Test-ValueFromPipelineByPropertyName{
param(
[Parameter(Mandatory, ValueFromPipelineByPropertyName)]
[string[]]$ComputerName
)
Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}
次に、 ComputerName プロパティを使用してオブジェクトをパイプするデモを次に示します。
[pscustomobject]@{ ComputerName = "HelloWorld" } |
Test-ValueFromPipelineByPropertyName
Saw that ComputerName was 'HelloWorld'
注意
パイプライン入力 () またはby PropertyName (by Value) を受け入れる型指定されたパラメーターを使用すると、 パラメーターで遅延バインド スクリプト ブロックを使用できます。
遅延バインド スクリプト ブロックは、ParameterBinding 中に自動的に実行されます。 結果は パラメーターにバインドされます。 遅延バインディングは、 ScriptBlock 型または System.Object 型として定義されたパラメーターでは機能しません。 スクリプト ブロックは呼び出 されず に渡されます。 遅延バインド スクリプト ブロックの詳細については、「about_Script_Blocks」を参照してください。
ValueFromRemainingArguments 引数
引数は ValueFromRemainingArguments 、パラメーターが、関数の他のパラメーターに割り当てられていないコマンド内のすべてのパラメーターの値を受け入れることを示します。
次の例では、必須の Value パラメーターと、関数に送信される残りのすべてのパラメーター値を受け入れる Remaining パラメーターを宣言します。
function Test-Remainder {
param(
[Parameter(Mandatory, Position=0)]
[string]$Value,
[Parameter(Position=1, ValueFromRemainingArguments)]
[string[]]$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
HelpMessage 引数
引数は HelpMessage 、パラメーターまたはその値の簡単な説明を含む文字列を指定します。 必須パラメーターを指定せずにコマンドを実行すると、PowerShell から入力を求められます。 ヘルプ メッセージを表示するには、プロンプトに「」と入力 !? し、Enter キーを押 します。
次の例では、必須の ComputerName パラメーターと、期待されるパラメーター値を説明するヘルプ メッセージを宣言します。
param(
[Parameter(Mandatory,
HelpMessage="Enter one or more computer names separated by commas.")]
[string[]]$ComputerName
)
出力例:
cmdlet at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:
関数に コメントベースのヘルプ がない場合、このメッセージは出力に Get-Help -Full 表示されます。
この引数は、省略可能なパラメーターには影響しません。
Alias 属性
Alias 属性は、 パラメーターの代替名を設定します。 パラメーターに割り当てることができるエイリアスの数に制限はありません。
次の例は、必須の ComputerName パラメーターに CN と MachineName のエイリアスを追加するパラメーター宣言を示しています。
param(
[Parameter(Mandatory)]
[Alias("CN","MachineName")]
[string[]]$ComputerName
)
資格情報属性
Credential 属性は、パラメーターが資格情報を受け入れることを示すために使用されます。 次の例は、 Credential 属性を使用するパラメーター宣言を示しています。
param(
[Parameter()]
[System.Management.Automation.Credential()]
[PSCredential]$Credential
)
試験的属性
Experimental 属性を使用して、一部のコードを試験段階として宣言します。 属性の詳細については、「 about_Experimental_Features」を参照してください。
PSDefaultValue 属性
PSDefaultValue は、スクリプト内のコマンド パラメーターの既定値を指定します。 この情報は、 コマンドレットによって Get-Help 表示されます。 既定値の情報を表示するには、関数にコメントベースのヘルプを含める必要があります。 例:
<#
.SYNOPSIS
This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
param(
[PSDefaultValue(Help='Current directory')]
[string]$Name = $PWD.Path
)
$Name
}
を使用して Get-Help 、既定値の情報を表示します。
Get-Help TestDefaultValue -Parameter name
-Name <String>
Required? false
Position? 1
Default value Current directory
Accept pipeline input? false
Accept wildcard characters? false
PSDefaultValue 属性引数
PSDefaultValue 属性には、次の 2 つの引数があります。
- ヘルプ - 既定値を記述する文字列。 この情報は、 コマンドレットによって
Get-Help表示されます。 - 値 - パラメーターの既定値。
どちらの引数も省略可能です。 引数を指定しない場合は、 Get-Help パラメーターに割り当てられた値が表示されます。
PSTypeName 属性
型宣言で拡張型名を使用することはできません。 PSTypeName* 属性を使用すると、パラメーターの型を拡張型に制限できます。
この例では、 コマンドレットは Test-Connection 拡張型を返します。 PSTypeName 属性を使用して、パラメーターの型を拡張型に制限できます。
function TestType {
param(
[PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
[psobject]$MtuStatus
)
$MtuStatus
}
$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu
System.Obsolete 属性
System.Obsolete 属性を使用して、サポートされなくなったパラメーターをマークします。 これは、関数からパラメーターを削除するが、 関数を使用する既存のスクリプトを中断したくない場合に便利です。
たとえば、型情報を出力に含めるかどうかを制御する NoTypeInformation スイッチ パラメーターを持つ関数を考えてみましょう。 この動作を既定値にし、 パラメーターを関数から削除します。 ただし、 関数を使用する既存のスクリプトを中断する必要はありません。 パラメーターを古いものとしてマークし、変更を説明するメッセージを追加できます。
param(
[System.Obsolete("The NoTypeInformation parameter is obsolete.")]
[SwitchParameter]$NoTypeInformation
)
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 に指示します。 パラメーター値がテストに失敗した場合、エラーが生成され、関数は呼び出されません。 パラメーターの検証は、指定された入力にのみ適用され、既定値などのその他の値は検証されません。
検証属性を使用して、ユーザーが変数に指定できる値を制限することもできます。
[AllowNull()] [int]$number = 7
検証属性は、パラメーターだけでなく、任意の変数に適用できます。 スクリプト内の任意の変数の検証を定義できます。
注意
型指定された変数で属性を使用する場合は、型の前に 属性を宣言することをお勧めします。
属性と変数名の前に改行を使用して型を宣言すると、その型は独自のステートメントとして扱われます。
[string]
[ValidateLength(1,5)] $Text = 'Okay'
IsPublic IsSerial Name BaseType
-------- -------- ---- --------
True True String System.Object
型の後に検証属性を宣言すると、型変換の前に割り当てられている値が検証されるため、予期しない検証エラーが発生する可能性があります。
[string] [ValidateLength(1,5)]$TicketIDFromInt = 43
[string] [ValidateLength(1,5)]$TicketIDFromString = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43
MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.
AllowNull 検証属性
AllowNull 属性を使用すると、必須パラメーターの値を にできます$null。 次の例では、null 値を指定できるハッシュテーブル ComputerInfo パラメーターを宣言します。
param(
[Parameter(Mandatory)]
[AllowNull()]
[hashtable]$ComputerInfo
)
注意
文字列型が null 値を受け入れないので、型コンバーターが string に設定されている場合、 AllowNull 属性は機能しません。 このシナリオでは 、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
)
次の例では、変数 $text の値は、1 文字以上、最大 10 文字である必要があります。
[ValidateLength(1,10)] [string] $text = 'valid'
ValidatePattern 検証属性
ValidatePattern 属性は、パラメーターまたは変数値と比較される正規表現を指定します。 値が正規表現パターンと一致しない場合、PowerShell はエラーを生成します。
次の例では、パラメーター値に 4 桁の数値が含まれている必要があり、各桁は 0 ~ 9 の数値である必要があります。
param(
[Parameter(Mandatory)]
[ValidatePattern("[0-9]{4}")]
[string[]]$ComputerName
)
次の例では、変数 $ticketID の値は 4 桁の数値である必要があり、各数字は 0 ~ 9 の数値である必要があります。
[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 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 の間である必要があります。
[ValidateRange(0,10)] [int]$number = 5
次の例では、変数 $number の値が 0 より大きい必要があります。
[ValidateRange("Positive")] [int]$number = 1
ValidateScript 検証属性
ValidateScript 属性は、パラメーターまたは変数値の検証に使用されるスクリプトを指定します。 PowerShell は値をスクリプトにパイプ処理し、スクリプトからが返 $false された場合、またはスクリプトが例外をスローした場合にエラーを生成します。
ValidateScript 属性を使用すると、検証対象の値が変数に$_マップされます。 変数を $_ 使用して、スクリプト内の値を参照できます。
次の例では、 EventDate パラメーターの値が現在の日付以上である必要があります。
param(
[Parameter(Mandatory)]
[ValidateScript({$_ -ge (Get-Date)})]
[DateTime]$EventDate
)
次の例では、変数 $date の値は現在の日時以下である必要があります。
[ValidateScript({$_ -le (Get-Date)})] [DateTime]$date = (Get-Date)
注意
ValidateScript を使用する場合、パラメーターに値を$null渡すことはできません。 Null 値を渡すと 、ValidateScript は引数を検証できません。
既定のエラー メッセージのオーバーライド
PowerShell 6 以降では、 引数で指定した値が無効な場合に生成される既定のエラー メッセージを ErrorMessage オーバーライドできます。 複合書式指定文字列を指定します。 インデックス コンポーネントは 0 、入力値を使用します。
インデックス コンポーネントは 1 、入力値の検証に使用される ScriptBlock を使用します。
次の例では、 EventDate パラメーターの値が現在の日付と時刻以上である必要があります。 値が無効な場合、指定した日付と時刻が古すぎることを示すエラー メッセージが表示されます。
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date)},
ErrorMessage = "{0} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
指定した値が過去の日付の場合は、カスタム エラー メッセージが返されます。
Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.
省略可能な書式指定文字列コンポーネントを使用して、文字列にさらに 書式設定を適用できます。
次の例では、 EventDate パラメーターの値が現在の日付と時刻以上である必要があります。 値が無効な場合、指定した日付が古すぎることがエラー メッセージに報告されます。
param(
[Parameter(Mandatory)]
[ValidateScript(
{$_ -ge (Get-Date).Date},
ErrorMessage = "{0:d} isn't a future date. Specify a later date."
)]
[DateTime]$EventDate
)
指定した値が過去の日付の場合は、カスタム エラー メッセージが返されます。
Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.
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できないことを指定します。 値が の場合、 $nullPowerShell は例外を発生させます。
ValidateNotNull 属性は、 パラメーターが省略可能で、型が未定義の場合、またはオブジェクトのような null 値を暗黙的に変換できない型コンバーターがある場合に使用するように設計されています。 文字列などの null 値を暗黙的に変換する型を指定した場合、ValidateNotNull 属性を使用している場合でも、null 値は空の文字列に変換されます。 このシナリオでは、 ValidateNotNullOrEmpty 属性を 使用します。
次の例では、 ID パラメーターの値を に $nullすることはできません。
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
ValidateNotNullOrEmpty 検証属性
ValidateNotNullOrEmpty 属性は、割り当てられた値を次のいずれかの値にできないことを指定します。
$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 自体によって内部的に使用され、外部使用を目的としたものではありません。