• 10/27/2020
  • 20 minutes to read
    • S
    • s
    • s
    • c
    • g

Short description

Explains how to add parameters to advanced functions.,

長い説明

記述する高度な関数にパラメーターを追加し、関数ユーザーがパラメーターとともに送信するパラメーター値を制限するために、useparameter属性と引数を

関数に追加するパラメーターは、PowerShellがすべてのコマンドレットと高度な関数に自動的に追加する一般的なパラメーターに加えて、ユーザーが使用できます。 PowerShell commonparametersの詳細については、”about_CommonParameters”を参照してください。

PowerShell3から始まります。,0の場合は、@Argsでsplattingを使用して、コマンドのパラメータを表すことができます。 スプラッティングは、単純で高度な機能で有効です。 詳細については、”about_Functions”および”about_splatting”を参照してください。

パラメーター値の型変換

differenttypeを期待するパラメーターに引数として文字列を指定すると、PowerShellは暗黙的に文字列をパラメーターターゲット型に変換します。高度な関数は、パラメータ値のカルチャ不変解析を実行します。

対照的に、カルチャに依存する変換は、コンパイルされたコマンドレットのparameterbinding中に実行されます。,

この例では、パラメーターを取るコマンドレットとスクリプト関数を作成します。 現在の文化は変更にドイツ語を設定します。ドイツ語形式の日付がパラメーターに渡されます。

Dienstag, 19. Juni 2018 00:00:00

上記のように、コマンドレットはカルチャに依存する解析を使用して文字列を変換します。

高度な関数は、カルチャ不変解析を使用し、次のエラーが発生します。

静的パラメーター

静的パラメーターは、関数内で常に使用可能なパラメーターです。,PowerShellコマ

次の例は、ComputerNameパラメータの宣言を示しています次の特性を持っています。

  • これは必須です（必須）。
  • これは、パイプラインからの入力を取ります。
  • これは、入力として文字列の配列を取ります。
Param( ] $ComputerName)

パラメータの属性

このセクションでは、関数パラメータに追加できる属性について説明します。

すべての属性は省略可能です。, ただし、CmdletBindingattributeを省略した場合、高度な関数として認識されるには、関数はParameter属性を挿入する必要があります。

各パラメータ宣言に一つまたは複数の属性を追加できます。 Parameterdeclarationに追加できる属性の数に制限はありません。

パラメーター属性

パラメーター属性は、functionparametersの属性を宣言するために使用されます。

Parameter属性はオプションであり、関数のパラメータのいずれも属性を必要としない場合は省略することができます。, ただし、単純な関数ではなく、拡張関数として認識されるには、関数にCmdletBinding属性またはParameter属性、またはその両方が必要です。

パラメーター属性には、パラメーターが必須か任意かなど、パラメーターの特性を定義する引数があります。

パラメーター属性、引数、および引数値を宣言するには、次の構文を使用します。 引数とそのvaluemustを囲む括弧は、パラメーターの後に空白を入れずに続きます。,

Param( $ParameterName)

かっこ内の引数を区切るには、カンマを使用します。 Parameter属性の二つの引数を宣言するには、followingsyntaxを使用します。

Param( )

パラメータ属性のブール引数の型は、デフォルトではパラメータ属性から省略されています。 引数の値を$trueに設定するか、引数を名前でリストします。 たとえば、followingParameter属性は同等です。,引数なしでParameter属性を使用する場合、CmdletBinding属性の代替として、引数名の後に続く括弧が必要になります。

Param( $ParameterName)

必須引数

Mandatory引数は、パラメータが必要であることを示します。 Thisargumentが指定されていない場合、パラメーターはオプションです。

次の例では、ComputerNameパラメーターを宣言します。 これは、パラメータを必須にするためにMandatory引数を使用します。,

Param( ] $ComputerName)

位置引数

Position引数は、パラメータがコマンドで使用されるときにパラメータ名が必要かどうかを決定します。 パラメーター宣言にPosition引数が含まれている場合、パラメーター名は省略でき、Powershellは、コマンド内の名前のないパラメーター値のlistof内の位置または順序によって、名前のないパラメーター値を識別します。,

Position引数が指定されていない場合、パラメーターがコマンドで使用されるたびに、パラメーター名、またはparameternameエイリアスまたは省略形は、パラメーター値の前に必ずパラメーター値の前に置かなければなりません。

デフォルトでは、すべての関数パラメータは位置です。 PowerShellは、関数でパラメータが宣言されている順序でパラメータにpositionnumbersを割り当てます。 この機能を無効にするには、CmdletBinding属性のPositionalBinding引数の値を$Falseに設定します。, Position引数は、CmdletBinding属性のPositionalBinding引数の値よりも優先されます。 詳細については、about_Functions_CmdletBindingAttributeの”PositionalBinding“を参照してください。

Position引数の値は整数として指定されます。 Positionvalue0はコマンドの最初の位置を表し、position valueof1はコマンドの二番目の位置を表します。,

関数に位置パラメーターがない場合、PowerShellはパラメーターが宣言される順序に基づいて各パラメーターに位置を割り当てます。しかし、ベストプラクティス、わされないようにこの割りになります。 パラメータを位置にしたい場合は、Position引数を使用します。

次の例では、ComputerNameパラメーターを宣言します。 これは、値が0のPosition引数を使用します。 その結果、-ComputerNameがコマンドからisomitted場合、その値はコマンド内の最初または名前のないparametervalueのみでなければなりません。,

Param( ] $ComputerName)

ParameterSetName引数

ParameterSetName引数は、aparameterが属するパラメータセットを指定します。 ていない場合のパラメータセットが指定されたパラメータが属するtoallのパラメータセットで定義されます。 したがって、一意であるためには、各パラメータセットには、他のパラメータセットのメンバーではない少なくとも一つのパラメータが必要です。

メモ

コマンドレットまたは関数には、32個のパラメーターセットに制限があります。,

次の例では、Computerパラメーター-セットでComputerNameパラメーター、Userパラメーター-セットでUserNameパラメーター、および両方のパラメーター-セットでaSummaryパラメーター

各引数にはParameterSetName値のみを指定でき、各パラメータ属性にはParameterSetName引数のみを指定できます。 Aparameterが複数のパラメーターセットに表示されることを示すには、追加のParameterattributesを追加します。,

次の例では、SummaryパラメーターをComputerおよびUserパラメーターセットに明示的に追加します。 Summaryパラメーターは、Computerパラメーターセットではオプションで、Userパラメーターセットでは必須です。

パラメーターセットの詳細については、”パラメーターセットについて”を参照

ValueFromPipeline引数

ValueFromPipeline引数は、パラメータがパイプラインオブジェクトから入力を受け入れることを示します。, 関数がオブジェクトのプロパティだけでなく、オブジェクトを受け入れる場合にこの引数を指定します。

次の例では、mandatoryandであるComputerNameパラメーターを宣言し、パイプラインから関数に渡されるオブジェクトを受け入れます。

Param( ] $ComputerName)

ValueFromPipelineByPropertyName引数

ValueFromPipelineByPropertyName引数は、パイプラインオブジェクトのプロパティからの入力をparameteracceptすることを示します。 オブジェクトプロパティは、パラメーターと同じ名前または別名を持ちます。,

たとえば、関数にComputerNameパラメーターがあり、pipedobjectにComputerNameプロパティがある場合、ComputerNamepropertyの値が関数のComputerNameパラメーターに割り当てられます。

次の例では、mandatoryandであるComputerNameパラメーターを宣言し、パイプラインを介して関数に渡されるオブジェクトのComputerNameプロパティからの入力を受け入れます。,

Param( ] $ComputerName)

注

パイプライン入力(by Value)または(by PropertyName)を受け入れる型指定されたパラメーターは、パラメーター上で遅延バインドスクリプトブロックを使用できるようにします。

delay-bindスクリプトブロックは、parameterbinding中に自動的に実行されます。 結果はパラメーターにバインドされます。 遅延バインディングは、タイプScriptBlockまたはSystem.Objectとして定義されたパラメーターでは機能しません。 スクリプトブロックは呼び出されずに渡されます。

delay-bindスクリプトブロックについて読むことができますhere about_Script_Blocks.md—–,

ValueFromRemainingArguments引数

ValueFromRemainingArguments引数は、パラメーターが関数の他のパラメーターに割り当てられていないコマンド内のパラメーターの値を受け入れることを示します。

次の例では、必須の値パラメーターと、関数に送信される残りのすべてのパラメーター値を受け入れるaRemainingパラメーターを宣言します。

Found 2 elements0: one1: two

注

PowerShell6.2より前では、ValueFromRemainingArgumentsコレクションはインデックス0の下に単一のエンティティとして結合されていました。,

HelpMessage引数

HelpMessage引数は、パラメータまたはその値の簡単な説明を含む文字列を指定します。 PowerShellは、必須のパラメーター値がコマンドにない場合に表示されるpromptthatにこのメッセージを表示します。 Thisargumentは省略可能なパラメーターには影響しません。

次の例では、必須のComputerNameパラメーターと、期待されるパラメーター値を説明するヘルプメッセージを宣言します。,

関数用の他のコメントベースのヘルプ構文がない場合（たとえば、.SYNOPSIS）、このメッセージはGet-Help出力にも表示されます。

Param( ] $ComputerName)

エイリアス属性

エイリアス属性は、パラメータの代替名を確立します。パラメーターに割り当てることができるエイリアスの数に制限はありません。

次の例は、必須のComputerNameパラメーターにCN andMachineNameエイリアスを追加するパラメーター宣言を示しています。,

Param( ] $ComputerName)

SupportsWildcards属性

SupportsWildcards属性は、parameteracceptsがワイルドカード値を受け取ることを示すために使用されます。 次の例は、パラメータdeclarationfor必須のパスのパラメータを支えるワイルドカード値です。

Param( ] $Path)

この属性を使用しても、ワイルドカードサポートは自動的には有効になりません。 Cmdletdeveloperは、ワイルドカード入力を処理するコードを実装する必要があります。 Wildcardssupportedは、基になるAPIまたはPowerShellプロバイダーによって異なります。 フォームアウト情報は、about_Wildcardsを参照してください。,

パラメーターおよび変数検証属性

検証属性は、高度な関数を呼び出すときにuserssubmitパラメーター値をテストするようにPowerShellに指示します。 パラメータ値がテストに失敗した場合、エラーが生成され、関数は呼び出されません。 パラメーターの検証は、指定された入力にのみ適用され、デフォルト値などの他の値は検証されません。

検証属性を使用して、ユーザーが変数に指定できる値を制限することもできます。, Avalidation属性とともに型コンバーターを使用する場合は、属性の前に型コンバーターを定義する必要があります。

 $number = 7

AllowNull検証属性

AllowNull属性を使用すると、必須パラメーターの値を$nullにすることができます。 次の例では、hashtable ComputerInfoパラメーターを宣言しますnull値を持つことができます。

Param( $ComputerInfo)

注意

AllowNull属性は、文字列型がnull値を受け入れないため、型コンバータがtostringに設定されている場合は機能しません。, このシナリオでは、allowemptystring属性を使用できます。

AllowEmptyString検証属性

AllowEmptyString属性を使用すると、必須パラメータの値を空の文字列("")にすることができます。 次の例では、空の文字列値を持つことができるComputerNameparameterを宣言します。

Param( $ComputerName)

AllowEmptyCollection検証属性

AllowEmptyCollection属性により、mandatoryparameterの値を空のコレクション@()にすることができます。, 次の例では、空のコレクション値を持つaComputerNameパラメーターを宣言します。

Param( ] $ComputerName)

ValidateCount検証属性

ValidateCount属性は、パラメーターが受け入れるパラメーター値の最小値と最大値を指定します。 PowerShellは、関数を呼び出すコマンドのパラメーター値の数がその範囲外である場合にエラーを生成します。

次のパラメーター宣言は、パラメーター値を一から五に受け取るComputerNameパラメーターを作成します。,

Param( ] $ComputerName)

ValidateLength検証属性

ValidateLength属性は、パラメータまたは変数値の文字の最小値と最大値を指定します。 PowerShellは、パラメーターまたは変数に指定された値の長さが範囲外である場合にエラーを生成します。

次の例では、各コンピューター名には一から十文字を使用する必要があります。

Param( ] $ComputerName)

次の例では、変数$numberの値は、長さが一文字の最小値で、最大十文字でなければなりません。,

$number = '01'

注

この例では、01の値は一重引quotesで囲まれています。 この属性は、ラップされていない数値を受け入れませんインクオート。

ValidatePattern検証属性

ValidatePattern属性は、パラメータまたは変数値と比較される正規表現を指定します。 PowerShellは、値が正規表現パターンと一致しない場合にエラーを生成します。,

次の例では、パラメータ値には四桁の数字を含める必要があり、各桁はゼロから九までの数字でなければなりません。

Param( ")] ] $ComputerName)

次の例では、変数$numberの値は正確に数字でなければなりません。

$")]$number = 1111

ValidateRange検証属性

ValidateRange属性は、各パラメーターまたは変数値に対して数値範囲またはaValidateRangeKind列挙値を指定します。PowerShellは、その範囲外の値がある場合にエラーを生成します。,

ValidateRangeKind列挙型では、次の値を使用できます。

  • Positive-ゼロより大きい数値。
  • 負-ゼロより小さい数。
  • 正でない-ゼロ以下の数値。
  • 負でない-ゼロ以上の数値。

次の例では、Attemptsパラメーターの値はゼロとtenの間にある必要があります。

Param( $Attempts)

次の例では、変数$numberの値は、zenzeroとtenの間でなければなりません。,

$number = 5

次の例では、変数$numberの値はゼロより大きくなければなりません。

$number = 1

ValidateScript検証属性

ValidateScript属性は、aparameterまたは変数値を検証するために使用されるスクリプトを指定します。 PowerShellは値をスクリプトにパイプし、スクリプトが$falseを返した場合、またはスクリプトが例外をスローした場合にエラーを生成します。,

ValidateScript属性を使用すると、検証されている値が$_変数にマップされます。 スクリプト内の値を参照するには、$_変数を使用できます。

次の例では、EventDateパラメーターの値は、現在の日付以上でなければなりません。

Param( $EventDate)

次の例では、変数$dateの値は、現在の日付と時刻以上でなければなりません。,

$date = (Get-Date)

注意

ValidateScriptを使用する場合、$null値をパラメータに渡すことはできません。 Null値を渡すと、ValidateScriptは引数を検証できません。

ValidateSet属性

ValidateSet属性は、parameteror変数の有効な値のセットを指定し、タブ補完を有効にします。 Aparameterまたは変数値がセット内の値と一致しない場合、PowerShellはエラーを生成します。 次の例では、Detailパラメーターの値はLow、Average、またはhighのみになります。,

Param( ] $Detail)

次の例では、変数$flavorの値は、chocolate、Strawberry、またはVanillaのいずれかでなければなりません。

$flavor = "Strawberry"

検証は、その変数がスクリプト内でも割り当てられるたびに発生します。 たとえば、次の場合、実行時にエラーが発生します。

Param( $Message)$Message = "bye"

動的バリデートセット値

クラスを使用して、ValidateSetatランタイムの値を動的に生成できます。, 次の例では、変数$Soundの有効な値は、利用可能なサウンドファイルのthreefilesystemパスをチェックするSoundNamesという名前のクラスを介して生成されます。

クラスは、

Param( )] $Sound)

ValidateNotNull検証属性

validatenotnull属性は、パラメータ値を$nullにできないことを指定します。 パラメーター値が$nullの場合、PowerShellはエラーを生成します。,

ValidateNotNull属性は、パラメータがisoptionalで、型が未定義の場合、またはobjectのようなnull値を変換できない型コンバータがある場合に使用するように設計されています。 文字列などのnull値を暗黙的に変換する型を指定すると、ValidateNotNullattributeを使用していてもnull値は空の文字列に変換されます。 このシナリオでは、ValidateNotNullOrEmpty

次の例では、IDパラメーターの値を$nullにすることはできません。,

Param( $ID)

ValidateNotNullOrEmpty検証属性

ValidateNotNullOrEmpty属性は、パラメーター値が$nullではなく、空の文字列("")にすることはできません。 PowerShellは、パラメーターが関数呼び出しで使用されているが、その値が$null、空の文字列("")、または空の配列@(),

Param( ] $UserName)

ValidateDrive検証属性

ValidateDrive属性は、パラメータ値が許可されたドライブのみを参照するパスを表現する必要があることを指定します。 パラメーター値が許可されているドライブ以外のドライブを参照している場合、PowerShellgeneratesエラー。 ドライブ自体を除くパスの存在は検証されません。

相対パスを使用する場合は、現在のドライブが許可されたドライブリストに含まれている必要があります。,

Param( $Path)

ValidateUserDrive検証属性

ValidateUserDrive属性は、パラメータ値がUserドライブを参照するパスを表す必要があることを指定します。 PowerShellは、パスが別のドライブを参照している場合にエラーを生成します。 検証属性のみパスのドライブ部分の存在をテストします。

相対パスを使用する場合、現在のドライブはUserでなければなりません。,

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument 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'. Cannotfind drive. A drive with the name 'User' does not exist.

Userドライブを十分な管理（JEA）セッション構成で定義できます。 この例では、User:driveを作成します。

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH
True

ValidateTrustedData検証属性

この属性はPowerShell6.1.1で追加されました。

現時点では、この属性はPowerShell自体によって内部的に使用され、外部使用のためのものではありません。,

動的パラメーター

動的パラメーターは、特定の条件下でのみ使用できるコマンドレット、関数、またはスクリプトのパラメーターです。

たとえば、いくつかのプロバイダーコマンドレットには、コマンドレットがプロバイダードライブまたはプロバイダードライブの特定のパスで使用され たとえば、Encodingパラメーターは、Add-Content、Get-Content、およびSet-Contentコマンドレットで使用できます。,

別のパラメーターがfunctionコマンドで使用されている場合、または別のパラメーターに特定の値がある場合にのみ表示されるパラメーターを作成することもで

動的パラメータは役に立ちますが、必要な場合にのみ使用します。 動的パラメーターを見つけるには、ユーザーがプロバイダーパスにあるか、Get-CommandコマンドレットのArgumentListパラメーターを使用するか、Get-HelpのPathパラメー

関数またはスクリプトの動的パラメーターを作成するには、DynamicParamキーワードを使用します。,

構文は次のとおりです。

DynamicParam {<statement-list>}

ステートメントリストで、Ifステートメントを使用して、パラメータが関数で使用できる条件を指定します。

aSystemを作成するには、New-Objectコマンドレットを使用します。マネジメント。自動化。RuntimeDefinedParameterパラメータを表すオブジェクトとその名前を指定します。

aSystemを作成するには、New-Objectコマンドを使用できます。マネジメント。自動化。,必須、位置、orValueFromPipelineまたはそのパラメーターセットなど、パラメーターのrepresentattributesを表すParameterAttributeオブジェクトです。

次の例は、標準パラメーター namedNameとPath、およびDP1というオプションの動的パラメーターを持つサンプル関数を示しています。 Dp1パラメータはPSet1パラメータセットにあり、Int32のタイプを持ちます。,DP1パラメーターは、Get-Sample関数で使用できるのは、Pathパラメーターの値がHKLM:で始まる場合のみで、HKEY_LOCAL_MACHINEレジストリドライブで使用されていることを示します。

詳細については、seeRuntimeDefinedParameterを参照してください。

スイッチパラメータ

スイッチパラメータは、パラメータ値のないパラメータです。 彼らは彼らが使用されているときにのみ有効であり、唯一の効果を持っています。

たとえば、powershellのNoProfileパラメーターです。exeはスイッチパラメータです。,

関数内にswitchパラメータを作成するには、パラメータ定義にSwitchタイプを指定します。

例：

Param(<ParameterName>)

または、別の方法を使用することができます：

Param( $<ParameterName>)

スイッチパラメータは使いやすく、より難しい構文を持つブールパラメータよりも

たとえば、switchパラメーターを使用するには、ユーザーはコマンドにパラメーターを入力します。

-IncludeAll

ブール値パラメータを使用するには、ユーザーはパラメータとブール値を入力します。,

-IncludeAll:$true

スイッチパラメータを作成するときは、パラメータ名を慎重に選択します。 パラメータ名は、パラメータの効果をユーザーに伝えることを忘れないでください。FilterやMaximumなど、avalueが必要であることを意味するあいまいな用語は避けてください。

ArgumentCompleter属性

ArgumentCompleter属性を使用すると、特定のパラメータにタブ補完値を追加できます。 ArgumentCompleter属性は、タブ補完が必要なforeachパラメーターで定義する必要があります。, DynamicParametersと同様に、利用可能な値は、ユーザーがパラメーター名の後にTabキーを押したときに実行時に計算されます。

ArgumentCompleter属性を追加するには、値を決定するスクリプトブロックを定義する必要があります。 スクリプトブロックは、以下のパラメーターを以下に指定した順序で取得する必要があります。 パラメータの名前は、値が位置的に指定されている場合には関係ありません。,

構文は次のとおりです。

ArgumentCompleterスクリプトブロック

スクリプトブロックパラメータは次の値に設定されます。

  • $commandName(Position0)-このパラメータは、スクリプトブロックがタブ補完を提供するコマンドの名前に設定されます。
  • $parameterName(Position1)-このパラメータは、whosevalueがタブ補完を必要とするパラメータに設定されます。
  • $wordToComplete（位置2）-このパラメータは、ユーザーがTabキーを押す前に提供した値に設定されます。, Scriptブロックは、この値を使用してタブ補完値を決定する必要があります。
  • $commandAst(Position3)-このパラメータは、現在の入力行の抽象SyntaxTree(AST)に設定されます。 詳しくは、”クラス”をご覧ください。
  • $fakeBoundParameters(Position4)-このパラメーターは、ユーザーがタブを押す前に、コマンドレットの$PSBoundParametersを含むハッシュテーブルに設定されます。 詳細については、”about_automatic_variables”を参照してください。,

ArgumentCompleterスクリプトブロックは、ForEach-Object、Where-Object、または別の適切なメソッドのように、pipelineを使用して値を展開する必要があります。値の配列を返すと、PowerShellは配列全体をタブ補完値として扱います。

次の例では、Valueパラメーターにタブ補完を追加します。 Valueパラメーターのみが指定されている場合は、valueに対して可能なすべての値または引数が表示されます。 する際にTypeパラメータが指定されたtheValueパラメータのディスプレイの可能値パターンを示すことが分かった。,

さらに、-like演算子は、ユーザーがfollowingcommandを入力してタブ補完を使用する場合、Appleのみが返されることを保証します。

Test-ArgumentCompleter -Type Fruits -Value A

も参照してください

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_functions_outputtypeattribute