about_Functions_CmdletBindingAttribute
簡単な説明
関数をコンパイル済みコマンドレットのように機能させる属性について説明します。
詳細な説明
この CmdletBinding
属性は、C# で記述されたコンパイル済みコマンドレットのように動作する関数の属性です。 コマンドレットの機能へのアクセスを提供します。
PowerShell は、コンパイルされたコマンドレットのパラメーターをバインドするのと同じ方法で、属性を持つ CmdletBinding
関数のパラメーターをバインドします。 $PSCmdlet
自動変数は属性を持つ関数でCmdletBinding
使用できますが$Args
、変数は使用できません。
属性を CmdletBinding
持つ関数では、不明なパラメーターと位置指定パラメーターが一致しない位置引数により、パラメーター バインドが失敗します。
Note
コンパイルされたコマンドレットでは、必須 Cmdlet
の属性が使用されます。これは、このトピックで説明する属性に似ています CmdletBinding
。
構文
次の例は、属性のすべての省略可能な引数を指定する関数の形式を CmdletBinding
示しています。 各引数の簡単な説明は、この例に従います。
{
[CmdletBinding(ConfirmImpact=<String>,
DefaultParameterSetName=<String>,
HelpURI=<URI>,
SupportsPaging=<Boolean>,
SupportsShouldProcess=<Boolean>,
PositionalBinding=<Boolean>)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
CmdletBinding 属性から省略すると、CmdletBinding 属性のブール値引数の型は既定でFalse になります。 引数の値を $true
名前で設定するか、単に引数を一覧表示します。 たとえば、次 の CmdletBinding 属性は同等です。
{
[CmdletBinding(SupportsPaging=$true)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
# Boolean arguments can be defined using this shorthand syntax
{
[CmdletBinding(SupportsPaging)]
Param ($Parameter1)
Begin{}
Process{}
End{}
}
ConfirmImpact
ConfirmImpact 引数は、ShouldProcess メソッドの呼び出しによって関数のアクションを確認するタイミングを指定します。 ShouldProcess メソッドの呼び出しでは、ConfirmImpact 引数が基本設定変数の値以上の場合にのみ、確認プロンプトが$ConfirmPreference
表示されます。 (引数の既定値は 中)。)この引数は、 SupportsShouldProcess 引数も指定されている場合にのみ指定します。
確認要求の詳細については、確認の要求を参照してください。
DefaultParameterSetName
DefaultParameterSetName 引数は、使用するパラメーター セットを判断できない場合に PowerShell が使用するパラメーター セットの名前を指定します。 各パラメーターの一意のパラメーターを必須パラメーターに設定することで、この問題を回避できます。
HelpURI
HelpURI 引数は、関数を説明するヘルプ トピックのオンライン バージョンのインターネット アドレスを指定します。 HelpURI 引数の値は、"http" または "https" で始まる必要があります。
HelpURI 引数の値は、関数に対して返される CommandInfo オブジェクトGet-Command
の HelpURI プロパティの値に使用されます。
ただし、ヘルプ ファイルがコンピューターにインストールされていて、ヘルプ ファイルの RelatedLinks セクションの最初のリンクの値が URI であるか、コメント ベースのヘルプの最初.Link
のディレクティブの値が URI である場合、ヘルプ ファイル内の URI が関数の HelpUri プロパティの値として使用されます。
このコマンドレットはGet-Help
、コマンドで Online パラメーターが指定されている場合に、HelpURI プロパティの値を使用して、関数ヘルプ トピックのGet-Help
オンライン バージョンを検索します。
SupportsPaging
SupportsPaging 引数は、First、Skip、IncludeTotalCount の各パラメーターを関数に追加します。 これらのパラメーターを使用すると、ユーザーは非常に大きな結果セットから出力を選択できます。 この引数は、SQL データベースなどのデータ選択をサポートする大規模なデータ ストアからデータを返すコマンドレットと関数用に設計されています。
この引数は、Windows PowerShell 3.0 で導入されました。
- First: 最初の 'n' オブジェクトのみを取得します。
- スキップ: 最初の 'n' オブジェクトを無視し、再メインオブジェクトを取得します。
- IncludeTotalCount: データ セット内のオブジェクトの数 (整数) の後にオブジェクトが続く数を報告します。 コマンドレットが合計カウントを特定できない場合は、"不明な合計カウント" を返します。
PowerShell には 、返される合計カウント値を取得し、合計カウント値の精度の見積もりを含むヘルパー メソッドである NewTotalCount が含まれています。
次のサンプル関数は、ページング パラメーターのサポートを高度な関数に追加する方法を示しています。
function Get-Numbers {
[CmdletBinding(SupportsPaging)]
param()
$FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
$LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
$FirstNumber - 1, 100)
if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
$TotalCountAccuracy = 1.0
$TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
$TotalCountAccuracy)
Write-Output $TotalCount
}
$FirstNumber .. $LastNumber | Write-Output
}
SupportsShouldProcess
SupportsShouldProcess 引数は、Confirm パラメーターと WhatIf パラメーターを関数に追加します。 Confirm パラメーターは、パイプライン内の各オブジェクトでコマンドを実行する前に、ユーザーにプロンプトを表示します。 WhatIf パラメーターは、コマンドを実行する代わりに、コマンドが行う変更を一覧表示します。
PositionalBinding
引数 PositionalBinding は、関数内のパラメーターが既定で位置指定されているかどうかを決定します。 既定値は $True
です。 位置バインドを無効にするには、引数の値$False
を指定して使用できます。
引数の 位置指定 は、Windows PowerShell 3.0 で導入されています。
パラメーターが位置指定の場合、パラメーター名は省略可能です。 PowerShell は、関数コマンドの名前のないパラメーター値の順序または位置に従って、名前のないパラメーター値を関数パラメーターに関連付けます。
パラメーターが位置指定されていない場合 ("名前付き") は、コマンドにパラメーター名 (または名前の省略形または別名) が必要です。
PositionalBinding が指定されている$True
場合、関数パラメーターは既定で位置指定されます。 PowerShell は、関数で宣言されている順序でパラメーターに位置番号を割り当てます。
PositionalBinding が指定されている$False
場合、関数パラメーターは既定では位置指定されません。 パラメーター属性の Position 引数がパラメーターで宣言されていない限り、パラメーターを関数で使用する場合は、パラメーター名 (または別名または省略形) を含む必要があります。
Parameter 属性の Position 引数は、PositionBinding の既定値よりも優先されます。 引数 Position を使用すると、パラメーターの位置の値を指定できます。 Position 引数の詳細については、「about_Functions_Advanced_Parameters」を参照してください。
メモ
SupportsTransactions 引数は、高度な関数ではサポートされていません。
キーワード
about_Functions_CmdletBinding_Attribute
関連項目
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示