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 値を持つよう、ブール値の 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-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 パラメーターの値が始まり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 属性は省略可能であり、関数のどのパラメーターにも属性が必要ない場合は省略できます。 ただし、単純な関数ではなく高度な関数として認識するには、コマンドレット バインド属性または 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引数のみを指定できます。 複数のパラメーター セットにパラメーターを含めるには、パラメーター属性を追加します。
次の例では、Summary パラメーターをパラメーター セットにUser明示的にComputer追加します。 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
)
次の引数を使用して関数を実装することを検討してください。
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 Valueby PropertyName) を受け入れる型指定されたパラメーターを使用すると、パラメーターで遅延バインド スクリプト ブロックを使用できます。
遅延バインド スクリプト ブロックは、ParameterBinding 中に自動的に実行されます。 結果はパラメーターにバインドされます。 遅延バインディングは、ScriptBlock または System.Object 型として定義されたパラメーターでは機能しません。 スクリプト ブロックは呼び出されずに渡されます。 遅延バインド スクリプト ブロックの詳細については、about_Script_Blocksを参照してください。
ValueFromReメインingArguments 引数
引数は ValueFromRemainingArguments 、パラメーターが、関数の他のパラメーターに割り当てられていないコマンド内のすべてのパラメーターの値を受け入れることを示します。
次の例では、必須の Value パラメーターと、関数に送信されるすべての reメイン パラメーター値を受け取る Reメインing パラメーターを宣言します。
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
)
SupportsWildカードs 属性
SupportsWildカードs 属性は、パラメーターがワイルドカード値を受け入れることを示すために使用されます。 次の例は、ワイルドカード値をサポートする必須の Path パラメーターのパラメーター宣言を示しています。
param(
[Parameter(Mandatory)]
[SupportsWildcards()]
[string[]]$Path
)
この属性を使用しても、ワイルドカードサポートは自動的に有効になりません。 コマンドレット開発者は、野生のカード入力を処理するコードを実装する必要があります。 サポートされるワイルドカードは、基になる API または PowerShell プロバイダーによって異なる場合があります。 詳細については、about_Wildカードを参照してください。
引数の入力候補属性
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
文字列型が null 値を受け取らないので、型コンバーターが文字列に設定されている場合、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)
Note
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
)
Note
このクラスは IValidateSetValuesGenerator PowerShell 6.0 で導入されました
ValidateNotNull 検証属性
ValidateNotNull 属性は、パラメーター値を指定できないこと$nullを指定します。 値が指定されている場合、PowerShell によって $null例外が発生します。
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 管理istration (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
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示