about_Functions_Advanced_Parameters
簡単な説明
高度な関数にパラメーターを追加する方法について説明します。
詳細な説明
記述する高度な関数にパラメーターを追加し、パラメーターの属性と引数を使用して、関数ユーザーがパラメーターと共に送信するパラメーター値を制限できます。
CmdletBinding属性を使用すると、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 値になります。
たとえば、Get-ChildItemの Recurse パラメーターは switch パラメーターです。
関数に switch パラメーターを作成するには、パラメーター定義で switch 型を指定します。
たとえば、関数には、データをバイト配列として出力するオプションがあります。
param([switch]$AsByteArray)
スイッチ パラメーターは使いやすく、PowerShell の構文が少ないブール型パラメーターよりも優先されます。
たとえば、switch パラメーターを使用するには、ユーザーがコマンドでパラメーターを入力します。
-IncludeAll
ブール値パラメーターを使用するには、ユーザーがパラメーターとブール値を入力します。
-IncludeAll $true
スイッチ パラメーターを作成するときは、パラメーター名を慎重に選択します。 パラメーター名がパラメーターの効果をユーザーに伝えるようにしてください。 Filter や Maximum など、値が必要であることを意味するあいまいな用語は避けてください。
スイッチ パラメーターの設計に関する考慮事項
スイッチ パラメーターには既定値を指定しないでください。 既定値は常に false にする必要があります。
スイッチ パラメーターは、既定では位置指定パラメーターから除外されます。 他のパラメーターが暗黙的に位置指定されている場合でも、スイッチ パラメーターは配置されません。 パラメーター属性でオーバーライドが、ユーザーを混乱させる可能性があります。
スイッチ パラメーターを設定すると、コマンドが既定の動作からあまり一般的でない、または複雑なモードに移動するように設計する必要があります。 コマンドの最も簡単な動作は、スイッチ パラメーターを使用する必要のない既定の動作です。
スイッチ パラメーターは必須にしないでください。 switch パラメーターを必須にする必要がある唯一のケースは、パラメーター セットを区別する必要がある場合です。
ブール値からの切り替えを明示的に設定するには、
-MySwitch:$boolValueと$params = @{ MySwitch = $boolValue }を使用したスプラッティングを使用します。スイッチ パラメーターは
SwitchParameter型であり、暗黙的にブール型に変換されます。 パラメーター変数は、条件式で直接使用できます。 次に例を示します。if ($MySwitch) { ... }書く必要はありません
if ($MySwitch.IsPresent) { ... }
動的パラメーター
動的パラメーターは、特定の条件下でのみ使用できるコマンドレット、関数、またはスクリプトのパラメーターです。
たとえば、いくつかのプロバイダー コマンドレットには、プロバイダー ドライブまたはプロバイダー ドライブの特定のパスでコマンドレットが使用されている場合にのみ使用できるパラメーターがあります。 たとえば、 Encoding パラメーターは、ファイル システム ドライブで使用されている場合にのみ、 Add-Content、 Get-Content、および Set-Content コマンドレットで使用できます。
関数コマンドで別のパラメーターが使用されている場合、または別のパラメーターに特定の値がある場合にのみ表示されるパラメーターを作成することもできます。
動的パラメーターは便利ですが、ユーザーが検出するのが困難な場合があるため、必要な場合にのみ使用します。 動的パラメーターを検索するには、ユーザーがプロバイダー パスに存在するか、Get-Command コマンドレットの ArgumentList パラメーターを使用するか、Get-Helpの Path パラメーターを使用する必要があります。
関数またはスクリプトの動的パラメーターを作成するには、 dynamicparam キーワードを使用します。
構文は次のとおりです。
dynamicparam {<statement-list>}
ステートメントの一覧で、 if ステートメントを使用して、関数でパラメーターを使用できる条件を指定します。
次の例は、 Name および Path という名前の標準パラメーターを持つ関数と、 KeyCount という名前の省略可能な動的パラメーターを示しています。 KeyCount パラメーターは、ByRegistryPath パラメーター セット内にあり、Int32の型を持っています。 KeyCount パラメーターは、Path パラメーターの値が HKLM: で始まり、HKEY_LOCAL_MACHINE レジストリ ドライブで使用されていることを示す場合にのみ、Get-Sample関数で使用できます。
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 パラメーターを宣言します。 値が 0 のPosition引数を使用します。 その結果、コマンドから -ComputerName を省略した場合、その値はコマンドの最初のパラメーター値または唯一の名前のないパラメーター値である必要があります。
param(
[Parameter(Position=0)]
[string[]]$ComputerName
)
ParameterSetName 引数
ParameterSetName引数は、パラメーターが属するパラメーター セットを指定します。 パラメーター セットが指定されていない場合、パラメーターは関数によって定義されているすべてのパラメーター セットに属します。 一意にするには、各パラメーター セットに、他のパラメーター セットのメンバーではないパラメーターが少なくとも 1 つ必要です。
Note
コマンドレットまたは関数の場合、パラメーター セットは 32 個に制限されています。
次の例では、Computer パラメーター セットの ComputerName パラメーター、User パラメーター セットの UserName パラメーター、および両方のパラメーター セットの Summary パラメーターを宣言します。
param(
[Parameter(Mandatory, ParameterSetName="Computer")]
[string[]]$ComputerName,
[Parameter(Mandatory, ParameterSetName="User")]
[string[]]$UserName,
[Parameter()]
[switch]$Summary
)
各引数には 1 つのParameterSetName値のみを指定でき、各Parameter属性には 1 つのParameterSetName引数のみを指定できます。 複数のパラメーター セットにパラメーターを含めるには、 Parameter 属性を追加します。
次の例では、 Summary パラメーターを Computer および User パラメーター セットに明示的に追加します。 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 パラメーター セット」を参照してください。
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'
Note
パイプライン入力 (by Value) または (by PropertyName) を受け取る型指定されたパラメーターを使用すると、パラメーターに対して delay-bind スクリプト ブロックを使用できます。
delay-bind スクリプト ブロックは、ParameterBinding 中に自動的に実行されます。 結果はパラメーターにバインドされます。 遅延バインディングは、型 ScriptBlock または System.Object として定義されているパラメーターでは機能しません。 スクリプト ブロックは、呼び出を介して渡されます。 delay-bind スクリプト ブロックの詳細については、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 属性は、パラメーターが資格情報を受け入れることを示すために使用されます。 次の例は、 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
検証属性は、パラメーターだけでなく、任意の変数に適用できます。 スクリプト内の任意の変数の検証を定義できます。
Note
型指定された変数で属性を使用する場合は、型の前に属性を宣言することをお勧めします。
属性と変数名の前に改行を指定して型を宣言すると、その型は独自のステートメントとして扱われます。
[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
)
Note
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
)
次の例では、変数 $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 列挙型では、次の値を使用できます。
Positive- 0 より大きい数値。Negative- 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)
Note
ValidateScript を使用する場合、パラメーターに$null値を渡すことはできません。 null 値 ValidateScript を渡すと 引数を検証できません。
既定のエラー メッセージのオーバーライド
PowerShell 6 以降では、指定した値が ErrorMessage 引数で無効な場合に生成される既定のエラー メッセージをオーバーライドできます。 composite 書式指定文字列を指定します。 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 値
Class を使用すると、実行時に ValidateSet の値を動的に生成できます。 次の例では、使用可能なサウンド ファイルの 3 つのファイルシステム パスをチェックする SoundNames という名前の Class を使用して、変数$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
)
Note
IValidateSetValuesGenerator クラスは PowerShell 6.0 で導入されました
ValidateNotNull 検証属性
ValidateNotNull 属性は、パラメーター値を$nullできないことを指定します。 値が $nullされると、PowerShell によって例外が発生します。
ValidateNotNull 属性は、パラメーターが省略可能で、型が未定義の場合、または型コンバーターを持ち、object のような null 値を暗黙的に変換できない場合に使用するように設計されています。 string などの null 値を暗黙的に変換する型を指定した場合、ValidateNotNull 属性を使用している場合でも、null 値は空の文字列に変換されます。 このシナリオでは、 ValidateNotNullOrEmpty 属性を使用します。
次の例では、 ID パラメーターの値を $nullできません。
param(
[Parameter()]
[ValidateNotNull()]
$ID
)
ValidateNotNullOrEmpty 検証属性
ValidateNotNullOrEmpty 属性は、割り当てられた値を次のいずれかの値にできないことを指定します。
$null- 空の文字列 (
"") - 空の配列 (
@())
値が無効な場合、PowerShell によって例外が発生します。
param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string[]]$UserName
)
ValidateNotNullOrWhiteSpace 検証属性
ValidateNotNullOrWhiteSpace 属性は、割り当てられた値を次のいずれかの値にできないことを指定します。
$null- 空の文字列 (
"") - 空の配列
@() - タブ、スペース、復帰、改行などの空白文字のみを含む文字列
- 空または空白文字のみを含む文字列を含む配列
値が無効な場合、PowerShell によって例外が発生します。
param(
[Parameter(Mandatory)]
[ValidateNotNullOrWhiteSpace()]
[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 自体によって内部的に使用され、外部での使用を目的としたものではありません。
関連項目
PowerShell