ja-JP/about_Functions_Advanced_Parameters.help.txt
|
TOPIC about_Functions_Advanced_Parameters 簡単な説明 アドバンス関数にパラメーターを追加する方法を説明します。 詳細な説明 自分で記述するアドバンス関数にパラメーターを追加し、パラメーター属性 と引数を使用して、関数の利用者がパラメーターで指定できる値を制限でき ます。 CmdletBinding 属性を使用すると、PowerShell は自動的に共通パラメーター を追加します。共通パラメーターと同じ名前のパラメーターは作成できませ ん。詳細については、about_CommonParameters を参照してください。 PowerShell 3.0 以降では、コマンド内のパラメーターを表すために @args を 使用したスプラッティングを使用できます。スプラッティングは単純関数と アドバンス関数の両方で有効です。詳細については、about_Functions と about_Splatting を参照してください。 パラメーターの宣言 パラメーターは、関数またはスクリプトブロックの param() ステートメント 内で宣言される変数です。オプションの [Parameter()] 属性を単独で、ある いは [Alias()] 属性や任意のパラメーター検証属性と組み合わせて使用でき ます。 パラメーター名は変数名の規則に従います。パラメーター名は十進数字、英字、 およびアンダースコアで構成されます。命名規則の完全な一覧については、 about_Variables を参照してください。 重要: 十進数字で始まるパラメーターを定義することは可能です。ただし、 PowerShell はそれらを位置指定パラメーターとして渡される文字列値として 扱うため、数字で始まるパラメーター名は推奨されません。 次の例を考えてみます。 function TestFunction { param ( [switch] $100, [string] $200 ) "100: $100" "200: $200" } これらのパラメーターを使用しようとすると、PowerShell はそれらを位置指 定パラメーターとして渡される文字列として解釈します。 PS> TestFunction -100 -200 Hello 100: False 200: -100 $args: -200 Hello 出力からは、PowerShell が値 -100 を $200 パラメーター変数にバインドし たことが分かります。残りの位置指定値は $args にバインドされます。この 問題を回避するには、スプラッティングを使用してパラメーター値を渡しま す。 PS> $ht = @{100 = $true; 200 = 'Hello'} PS> TestFunction @ht 100: True 200: Hello $args: 詳細については、about_Splatting を参照してください。 パラメーター値の型変換 異なる型を期待するパラメーターに引数として文字列を指定すると、 PowerShell は文字列をパラメーターの対象の型に暗黙的に変換します。アド バンス関数はパラメーター値のカルチャー非依存の解析を行います。 対照的に、コンパイル済みコマンドレットではパラメーターバインド中にカル チャー依存の変換が行われます。 次の例では、[datetime] パラメーターを受け取るコマンドレットとスクリプ ト関数を作成します。現在のカルチャーをドイツ語設定に変更します。ドイツ 語形式の日付がパラメーターに渡されます。 # [datetime] 引数を受け取るコマンドレットを作成します。 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 上記のとおり、コマンドレットはカルチャー依存の解析を使用して文字列を変 換します。 # 同等の関数を定義します。 function Get-Date_Func { param( [datetime] $Date ) process { $Date } } [cultureinfo]::CurrentCulture = 'de-DE' # このドイツ語形式の日付文字列は非依存カルチャーでは機能しません。 # 例: [datetime] '19-06-2018' は失敗します。 $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." 詳細については、about_Type_Conversion を参照してください。 静的パラメーター 静的パラメーターは、関数内で常に使用可能なパラメーターです。PowerShell のコマンドレットおよびスクリプトのほとんどのパラメーターは静的パラメー ターです。 次の例は、以下の特性を持つ ComputerName パラメーターの宣言を示していま す。 - 必須である。 - パイプラインから入力を受け取る。 - 文字列の配列を入力として受け取る。 param( [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [string[]]$ComputerName ) [switch] パラメーター [switch] パラメーターは、パラメーター値を取らないパラメーターです。代 わりに、その存在または不在によってブール値の true または false を伝え ます。[switch] パラメーターが存在する場合は true 値を持ち、不在の場合 は false 値を持ちます。 たとえば、Get-ChildItem の Recurse パラメーターは [switch] パラメーター です。 次の例は、データをバイト配列として出力するオプションを提供するために使 用できる [switch] パラメーターの定義を示しています。 param([switch]$AsByteArray) [switch] パラメーターは使いやすく、PowerShell にとって構文が自然でない ブールパラメーターよりも好まれます。 [switch] パラメーターを使用するには、コマンドにパラメーターを含めます。 たとえば、次のとおりです。 -IncludeAll ブールパラメーターを使用するには、パラメーターとブール値を指定する必要 があります。 -IncludeAll $true [switch] パラメーターを作成するときは、パラメーター名を慎重に選んでくだ さい。パラメーター名がパラメーターの効果を利用者に伝えることを確認しま す。Filter や Maximum など、値が必要であることを暗示するあいまいな用語 は避けてください。 [switch] パラメーターの設計上の考慮事項 - [switch] パラメーターに既定値を設定しないでください。[switch] パラメ ーターは常に false が既定値です。 - [switch] パラメーターを位置指定にしないでください。既定では、[switch] パラメーターは位置指定パラメーターから除外されます。Parameter 属性で これをオーバーライドすることはできますが、利用者を混乱させる可能性が あります。 - [switch] パラメーターを使用すると、コマンドの既定の動作がより一般的で ない、またはより複雑なモードに変わるように設計してください。コマンド の最も単純な動作は、[switch] パラメーターの使用を必要としない既定の動 作であるべきです。 - [switch] パラメーターを必須にしないでください。[switch] パラメーター を必須にすることが役立つ唯一のケースは、パラメーターセットを区別する ために必要な場合です。 - [switch] パラメーター変数を条件式で直接使用します。SwitchParameter 型 は暗黙的にブール値に変換されます。たとえば、次のとおりです。 if ($MySwitch) { ... } - [switch] パラメーターによって制御される動作は、常にパラメーターの存在 ではなく値に基づいてください。[switch] パラメーターの存在をテストする 方法はいくつかあります。 - $PSBoundParameters に [switch] パラメーター名がキーとして含まれる - $MyInvocation.BoundParameters に [switch] パラメーター名がキーとし て含まれる - スイッチが一意のパラメーターセットを定義する場合の $PSCmdlet.ParameterSetName たとえば、-MySwitch:$false やスプラッティングを使用して、スイッチに 明示的な値を指定することが可能です。パラメーターの存在のみをテストす ると、スイッチの値が $false ではなく $true であるかのようにコマンド が動作します。 動的パラメーター 動的パラメーターは、特定の条件下でのみ使用可能なコマンドレット、関数、 またはスクリプトのパラメーターです。 たとえば、いくつかのプロバイダーコマンドレットには、そのコマンドレット がプロバイダードライブ内、またはプロバイダードライブの特定のパスで使用 される場合にのみ使用可能なパラメーターがあります。たとえば、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 属性は、関数パラメーターの属性を宣言するために使用します。 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)] ) # ブール引数はこの省略構文を使用して定義できます param( [Parameter(Mandatory)] ) CmdletBinding 属性を使用する代わりに引数なしで Parameter 属性を使用する 場合でも、属性名に続く括弧は依然として必要です。 param( [Parameter()] $ParameterName ) Mandatory 引数 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 つ必要です。 注: コマンドレットまたは関数には、32 個のパラメーターセットの制限があり ます。 次の例は、Computer パラメーターセットの ComputerName パラメーター、User パラメーターセットの UserName パラメーター、両方のパラメーターセットの Summary パラメーターを宣言します。 param( [Parameter(Mandatory, ParameterSetName="Computer")] [string[]]$ComputerName, [Parameter(Mandatory, ParameterSetName="User")] [string[]]$UserName, [Parameter()] [switch]$Summary ) 各引数で指定できる ParameterSetName 値は 1 つだけであり、各 Parameter 属性で指定できる ParameterSetName 引数は 1 つだけです。パラメーターを複 数のパラメーターセットに含めるには、追加の 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_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 Value) または (by PropertyName) で受け取る型 付きパラメーターでは、パラメーターで遅延バインドスクリプトブロックを使 用できます。 遅延バインドスクリプトブロックは、ParameterBinding 中に自動的に実行され ます。その結果がパラメーターにバインドされます。遅延バインドは、 ScriptBlock 型または System.Object 型として定義されたパラメーターでは機 能しません。スクリプトブロックは呼び出されずにそのまま渡されます。遅延 バインドスクリプトブロックの詳細については、about_Script_Blocks を参照し てください。 ValueFromRemainingArguments 引数 ValueFromRemainingArguments 引数は、関数の他のパラメーターに割り当てら れていないコマンド内のすべてのパラメーター値をパラメーターが受け取るこ とを示します。 次の例は、必須の Value パラメーターと、関数に送信される残りすべてのパラ メーター値を受け取る Remaining パラメーターを宣言します。 function Test-Remainder { param( [Parameter(Mandatory, Position=0)] [string]$Value, [Parameter(ValueFromRemainingArguments, Position=1)] [string[]]$Remaining ) "Value = $Value" "Found $($Remaining.Count) remaining values" for ($i = 0; $i -lt $Remaining.Count; $i++) { "${i}: $($Remaining[$i])" } } PS> Test-Remainder first one two three Value = first Found 3 remaining values 0: one 1: two 2: three PowerShell 6.2 以降では、ValueFromRemainingArguments に渡されるコレクシ ョンの扱いが異なります。コレクションのみを渡す場合、コレクション内の各値 は個別の項目として扱われます。 PS> Test-Remainder first one, two, three Value = first Found 3 remaining values 0: one 1: two 2: three 少なくとも 1 つがコレクションでない複数の値を渡す場合、コレクションは単 一の項目として扱われます。 PS> Test-Remainder first one, two three four Value = first Found 3 remaining values 0: one two 1: three 2: four 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 の出力に表示されます。 この引数はオプションのパラメーターには効果がありません。 DontShow 引数 DontShow 値は通常、廃止されたパラメーターを削除できないコマンドの下位互 換性を支援するために使用されます。DontShow を True に設定すると、タブ展 開と IntelliSense でパラメーターが利用者から隠されます。 PowerShell v7 (以降) は、次の廃止されたパラメーターを隠すために DontShow を使用します。 - ConvertTo-Csv および Export-Csv の NoTypeInformation パラメーター - Format-Hex の Raw パラメーター - Invoke-RestMethod および Invoke-WebRequest の UseBasicParsing パラメ ーター DontShow 引数には次の副作用があります。 - DontShow が使用されていないパラメーターセットがある場合でも、関連付け られたパラメーターのすべてのパラメーターセットに影響します。 - 共通パラメーターをタブ補完と IntelliSense から隠します。DontShow は、 オプションの共通パラメーター WhatIf、Confirm、UseTransaction は隠しま せん。 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 属性 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 つの引数があります。 - Help - 既定値を説明する文字列。この情報は Get-Help コマンドレットによ って表示されます。 - Value - パラメーターの既定値。 両方の引数はオプションです。引数を指定しない場合、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 [switch] パラメーターを持つ関数を考えてみます。その動作を既定にして、関 数からパラメーターを削除したいとします。ただし、その関数を使用する既存 のスクリプトを壊したくありません。パラメーターを廃止としてマークし、変 更を説明するメッセージを追加できます。 param( [System.Obsolete("The NoTypeInformation parameter is obsolete.")] [switch]$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 検証属性は、パラメーターだけでなく任意の変数に適用できます。スクリプト 内の任意の変数に対して検証を定義できます。 注: 型付き変数で任意の属性を使用する場合は、型の前に属性を宣言するのが ベストプラクティスです。 属性と変数名の前に改行を入れて型を宣言すると、型はそれ自体が 1 つのステ ートメントとして扱われます。 [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 ) 注: AllowNull 属性は、型コンバーターが string に設定されている場合は機 能しません。string 型は 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) 注: 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 値 class を使用して、実行時に ValidateSet の値を動的に生成できます。次の例 では、変数 $Sound の有効な値は、利用可能なサウンドファイルについて 3 つ のファイルシステムパスをチェックする SoundNames という class を介して生 成されます。 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 にできないことを指定しま す。値が $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 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 自体によって内部的に使用され、外部での使用を意図 したものではありません。 この属性は PowerShell 6.1.1 で追加されました。 関連項目 about_Automatic_Variables about_Functions about_Functions_Advanced about_Functions_Advanced_Methods about_Functions_CmdletBindingAttribute about_Functions_OutputTypeAttribute ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |