about_Functions_Advanced_Parameters
トピック
about_Functions_Advanced_Parameters
簡易説明
CmdletBinding 属性を宣言する関数に静的パラメーターと動的パラメーターを追加する方法に
ついて説明します。
詳細説明
関数を作成した場合、独自のパラメーターを宣言することができ、コンパイル済みコマン
ドレットから利用可能な共通パラメーターにアクセスできる関数を作成することができます。
Windows PowerShell の共通パラメーターの詳細については、「about_CommonParameters」を参照してください。
静的パラメーター
次の例は、ComputerName パラメーターを定義するパラメーター宣言を示しています。このパラメ
ーターの特性は次のとおりです。
- 必須です。
- パイプラインから入力を取得します。
- 文字列の配列を入力として取得します。
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
パラメーターを宣言する場合に使用する必要がある唯一の必須属性は、パラメーター属性です。ただ
し、Alias 属性およびいくつかの検証引数も宣言できます。パラメーター宣言に追加できる属性の数
に制限はありません。
パラメーター属性
パラメーター属性は、関数のパラメーターを宣言する場合に使用します。この属性は、パラメーター
は必須か省略可能かなど、パラメーターの特性を定義するのに使用する次の名前付き引数を備えています。
Mandatory 名前付き引数
Mandatory 引数は、関数の実行時にパラメーターが必須であることを示します。この引数を指定
しない場合、パラメーターは省略可能なパラメーターになります。次の例は、関数の実行時に必要
なパラメーターの宣言を示しています。
Param
(
[parameter(Mandatory=$true)]
[String[]]
$ComputerName
)
Position 名前付き引数
Position 引数は、パラメーターの位置を指定します。この引数を指定しない場合、パラメー
ターの設定時にパラメーター名またはそのエイリアスを明示的に指定する必要があります。また、
関数のパラメーターのどれにも位置がない場合、Windows PowerShell ランタイムは、パラメ
ーターの受け取り順序に基づいて各パラメーターに位置を割り当てます。
次の例は、コマンドレットの実行時に 1 番目の引数として値を指定する必要があるパラメータ
ーの宣言を示しています。この関数は、パラメーターの名前の指定の有無にかかわらず、実行できます。
Param
(
[parameter(Position=0)]
[String[]]
$ComputerName
)
ParameterSetName 名前付き引数
ParameterSetName 引数には、パラメーターが属するパラメーター セットを指定します。パ
ラメーター セットを指定しない場合、パラメーターは、関数によって定義されるすべてのパラメ
ーター セットに属します。この動作では、各パラメーター セットは、その他のパラメーター セ
ットのメンバーではない 1 つの固有パラメーターを備えている必要があります。次の例は、2 つ
の異なるパラメーター セットに属する 2 つのパラメーターのパラメーター宣言を示しています。
Param
(
[parameter(Mandatory=$true,
ParameterSetName="Computer")]
[String[]]
$ComputerName
)
Param
(
[parameter(Mandatory=$true,
ParameterSetName="User")]
[String[]]
$UserName
)
パラメーター セットの詳細については、MSDN ライブラリの「Cmdlet Parameters (コマンドレッ
ト パラメーター)」(https://go.microsoft.com/fwlink/?LinkId=142183) を参照してください。
ValueFromPipeline 名前付き引数
ValueFromPipeline 引数には、パイプライン オブジェクトからの入力をパラメーターが受
け取ることを指定します。コマンドレットがオブジェクトのプロパティではなく、完全なオブジ
ェクトにアクセスする場合は、この引数を指定します。次の例は、パイプラインから関数に渡され
る入力オブジェクトを受け取る必須の ComputerName パラメーターのパラメーター宣言を示し
ています。
Param
(
[parameter(Mandatory=$true,
ValueFromPipeline=$true)]
[String[]]
$ComputerName
)
ValueFromPipelineByPropertyName 名前付き引数
valueFromPipelineByPropertyName 引数には、パイプライン オブジェクトのプロパティ
からの入力をパラメーターが受け取ることを指定します。次の条件を満たす場合にこの属性を指定します。
- パラメーターは、パイプで渡されるオブジェクトのプロパティにアクセスする。
- プロパティの名前がパラメーターと同じであるか、またはプロパティのエイリアスがパ
ラメーターと同じである。
たとえば、関数に ComputerName パラメーターがあり、パイプで渡されるオブジェクトに
ComputerName プロパティがある場合、ComputerName プロパティの値が、関数の
ComputerName パラメーターに代入されます。
次の例は、コマンドレットに渡される入力オブジェクトの ComputerName プロパティからの
入力を受け取る ComputerName パラメーターのパラメーター宣言を示しています。
Param
(
[parameter(Mandatory=$true,
ValueFromPipelineByPropertyName=$true)]
[String[]]
$ComputerName
)
ValueFromRemainingArguments 名前付き引数
ValueFromRemainingArguments 引数には、パラメーターが、関数のパラメーターにバイン
ドされていない残りの引数のすべてを受け取ることを指定します。次の例は、関数に渡される入力
オブジェクトの残りのすべての引数を受け取る ComputerName パラメーターのパラメーター宣言
を示しています。
Param
(
[parameter(Mandatory=$true,
ValueFromRemainingArguments=$true)]
[String[]]
$ComputerName
)
HelpMessage 名前付き引数
HelpMessage 引数には、パラメーターの簡易説明を含むメッセージを指定します。次の例は、
パラメーターの説明を提供するパラメーター宣言を示しています。
Param
(
[parameter(Mandatory=$true,
HelpMessage="An array of computer names.")]
[String[]]
$ComputerName
)
Alias 属性
Alias 属性には、パラメーターの別の名前を指定します。パラメーターに割り当てることができ
るエイリアスの数に制限はありません。次の例は、ComputerName パラメーターにエイリアス
"CN" を追加する、必須パラメーターの宣言を示しています。
Param
(
[parameter(Mandatory=$true)]
[alias("CN")]
[String[]]
$ComputerName
)
パラメーター検証属性
これらの属性には、Windows PowerShell ランタイムが高度な関数の引数を検証する方法を定義
します。
AllowNull 検証属性
AllowNull 属性では、必須コマンドレット パラメーターの引数を Null に設定することがで
きます。次の例では、ComputerName パラメーターに、このパラメーターが必須パラメーターで
はなくても、Null の値を含めることができます。
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowNull()]
$ComputerName
)
AllowEmptyString 検証属性
AllowEmptyString 属性では、空の文字列を必須コマンドレット パラメーターの引数にすること
ができます。次の例では、ComputerName パラメーターに、このパラメーターが必須パラメータ
ーではなくても、空の文字列 ("") を含めることができます。
Param
(
[parameter(Mandatory=$true)]
[String]
[AllowEmptyString()]
$ComputerName
)
AllowEmptyCollection 検証属性
AllowEmptyCollection 属性では、空のコレクションを必須パラメーターの引数にすることができ
ます。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[AllowEmptyCollection()]
$ComputerName
)
ValidateCount 検証属性
ValidateCount 属性には、パラメーターが受け取ることができる引数の最小数と最大数を指
定します。引数の数がその範囲を超えると、Windows PowerShell ランタイムはエラーを生成
します。次の例は、1 ～ 5 個の引数を受け取ることができる ComputerName パラメーターです。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateCount(1,5)]
$ComputerName
)
ValidateLength 検証属性
ValidateLength 属性には、パラメーター引数の最小の長さと最大の長さを指定します。パラメー
ター引数の長さがその範囲を超えると、Windows PowerShell ランタイムはエラーを生成しま
す。次の例では、指定したコンピューター名は 1 ～ 10 文字で構成されている必要があります。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateLength(1,10)]
$ComputerName
)
ValidatePattern 検証属性
ValidatePattern 属性には、パラメーター引数のパターンを検証する正規表現を指定します。パラ
メーター引数がそのパターンと一致しない場合は、Windows PowerShell ランタイムはエラー
を生成します。次の例では、パラメーターの引数は 4 桁の数字である必要があり、各桁は 0 ～
9 の数字である必要があります。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
$ComputerName
)
ValidateRange 検証属性
ValidateRange 属性には、パラメーター引数の最小値と最大値を指定します。パラメーター引数が
その範囲を超えると、Windows PowerShell ランタイムはエラーを生成します。次の例では、
パラメーターの引数に 0 未満または 10 を超える値を指定できません。
Param
(
[parameter(Mandatory=$true)]
[Int[]]
[ValidateRange(0,10)]
$Count
)
ValidateScript 検証属性
ValidateScript 属性には、パラメーター引数の検証に使用するスクリプトを指定します。ス
クリプトの結果が False であるか、またはスクリプトが例外をスローする場合、Windows
PowerShell ランタイムはエラーを生成します。次の例では、Count パラメーターの値は 4 未
満である必要があります。
Param
(
[parameter()]
[Int]
[ValidateScript({$_ -lt 4})]
$Count
)
ValidateSet 属性
ValidateSet 属性には、パラメーター引数の有効値のセットを指定します。パラメーター引数
がセットの値と一致しない場合、Windows PowerShell ランタイムはエラーを生成します。
次の例では、パラメーターの引数には、Steve、Mary、または Carl という名前しか指定でき
ません。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateRange("Steve", "Mary", "Carl")]
$UserName
)
ValidateNotNull 検証属性
ValidateNotNull 属性には、パラメーター引数を Null に設定できないことを指定します。
パラメーター値が Null の場合、Windows PowerShell ランタイムはエラーを生成します。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNull()]
$UserName
)
ValidateNotNullOrEmpty 検証属性
ValidateNotNullOrEmpty 属性には、パラメーターの引数を Null に設定できず、空にもで
きないことを指定します。パラメーターが指定されていても、その値が Null、空の文字列、
または空の配列である場合、Windows PowerShell ランタイムはエラーを生成します。
Param
(
[parameter(Mandatory=$true)]
[String[]]
[ValidateNotNullOrEmpty()]
$UserName
)
動的パラメーター
動的パラメーターとは、特定の条件が満たされた場合にのみ利用できる、コマンドレット、関数、
またはスクリプトのパラメーターです。
たとえば、いくつかのプロバイダー コマンドレットには、そのコマンドレットを特定のプロバ
イダー パスで使用した場合にのみ指定できるパラメーターが用意されています。よく使用され
る動的パラメーターの 1 つとして、Set-Item コマンドレットの Encoding パラメーターがあり
ます。これは、Set-Item コマンドレットを FileSystem プロバイダー パスで使用した場合にの
み指定できます。
関数またはスクリプトに動的パラメーターを作成するには、DynamicParam キーワードを使用し
ます。
構文は次のとおりです。
DynamicParam {<statement-list>}
ステートメント リストでは、If ステートメントを使用して、関数でパラメーターが有効になる
条件を指定します。
パラメーターを表す System.Management.Automation.RuntimeDefinedParameter オブジェクトを
作成し、パラメーター名を指定するには、New-Object コマンドレットを使用します。
また、New-Object コマンドを使用して System.Management.Automation.ParameterAttribute
オブジェクトを作成することで、Mandatory、Position、ValueFromPipeline などのパラメーター
の属性や、パラメーター セットを表すこともできます。
次の例は、Name および Path という標準パラメーターと、DP1 という省略可能な動的パラメー
ターを持つサンプル関数を示しています。DP1 パラメーターは、PSet1 パラメーター セットに
含まれる Int32 型のパラメーターです。Sample 関数に DP1 パラメーターを指定できるのは、
Path パラメーターの値に "HKLM:" が含まれている場合だけです。つまり、このパラメーターは
HKEY_LOCAL_MACHINE レジストリ ドライブで使用されます。
function Sample {
Param ([String]$Name, [String]$Path)
DynamicParam
{
if ($path -match "*HKLM*:")
{
$dynParam1 = new-object
System.Management.Automation.RuntimeDefinedParameter("dp1",
[Int32], $attributeCollection)
$attributes = new-object System.Management.Automation.ParameterAttribute
$attributes.ParameterSetName = 'pset1'
$attributes.Mandatory = $false
$attributeCollection = new-object
-Type System.Collections.ObjectModel.Collection``1[System.Attribute]
$attributeCollection.Add($attributes)
$paramDictionary = new-object
System.Management.Automation.RuntimeDefinedParameterDictionary
$paramDictionary.Add("dp1", $dynParam1)
return $paramDictionary
} End if
}
}
詳細については、MSDN (Microsoft Developer Network) ライブラリの
「RuntimeDefinedParameter クラス (英語ページの可能性があります)」
(https://go.microsoft.com/fwlink/?LinkID=145130) を参照してください。
関連項目
about_Advanced Functions
about_Functions_Advanced_Methods
about_Functions_CmdletBindingAttribute