ja-JP/about_Functions_CmdletBindingAttribute.help.txt
|
TOPIC about_Functions_CmdletBindingAttribute 簡単な説明 関数をコンパイル済みコマンドレットのように動作させる属性について説明し ます。 詳細な説明 CmdletBinding 属性は、関数を C# で記述されたコンパイル済みコマンドレッ トのように動作させる関数の属性です。コマンドレットの機能へのアクセスを 提供します。 CmdletBinding 属性を使用すると、PowerShell は自動的に共通パラメーターを 追加します。共通パラメーターと同じ名前のパラメーターは作成できません。 詳細については、about_CommonParameters を参照してください。 PowerShell は、CmdletBinding 属性を持つ関数のパラメーターを、コンパイル 済みコマンドレットのパラメーターをバインドするのと同じ方法でバインドし ます。$PSCmdlet 自動変数は CmdletBinding 属性を持つ関数で利用可能ですが、 $args 変数は利用できません。 CmdletBinding 属性を持つ関数では、不明なパラメーターおよび一致する位置 指定パラメーターのない位置指定引数により、パラメーターバインドが失敗し ます。 注: コンパイル済みコマンドレットは、このトピックで説明する CmdletBinding 属性に似た、必須の Cmdlet 属性を使用します。 構文 次の例は、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 {} } # ブール引数はこの省略構文を使用して定義できます { [CmdletBinding(SupportsPaging)] param ($Parameter1) begin {} process {} end {} } ConfirmImpact ConfirmImpact 引数は、関数のアクションが ShouldProcess メソッドの呼び出 しによって確認されるべきタイミングを指定します。ShouldProcess メソッド の呼び出しは、ConfirmImpact 引数が $ConfirmPreference 設定変数の値以上で ある場合にのみ確認プロンプトを表示します。(引数の既定値は Medium です。) この引数は、SupportsShouldProcess 引数も指定されている場合にのみ指定しま す。 確認要求の詳細については、Requesting Confirmation を参照してください。 DefaultParameterSetName DefaultParameterSetName 引数は、どのパラメーターセットを使用するかを判別 できない場合に PowerShell が使用しようとするパラメーターセットの名前を指 定します。各パラメーターセットの一意のパラメーターを必須パラメーターに することで、この問題を回避できます。 HelpUri HelpUri 引数は、関数を説明するヘルプトピックのオンライン版のインターネッ トアドレスを指定します。HelpUri 引数の値は "http" または "https" で始ま る必要があります。 HelpUri 引数の値は、Get-Command が関数に対して返す CommandInfo オブジェ クトの HelpUri プロパティの値として使用されます。 ただし、ヘルプファイルがコンピューターにインストールされており、ヘルプ ファイルの RelatedLinks セクションの最初のリンクの値が URI である場合、 またはコメントベースのヘルプの最初の .LINK キーワードの値が URI である場 合、ヘルプファイル内の URI が関数の HelpUri プロパティの値として使用され ます。 Get-Help コマンドレットは、Get-Help の Online パラメーターがコマンドで指 定されたときに、HelpUri プロパティの値を使用して関数ヘルプトピックのオン ライン版を見つけます。 SupportsPaging SupportsPaging 引数は、First、Skip、IncludeTotalCount パラメーターを関数 に追加します。これらのパラメーターを使用すると、利用者は非常に大きな結果 セットから出力を選択できます。この引数は、SQL データベースなど、データ選 択をサポートする大規模なデータストアからデータを返すコマンドレットおよび 関数のために設計されています。 この引数は Windows PowerShell 3.0 で導入されました。 - First: 最初の 'n' 個のオブジェクトのみを取得します。 - Skip: 最初の 'n' 個のオブジェクトを無視し、残りのオブジェクトを取得し ます。 - IncludeTotalCount: データセット内のオブジェクトの数 (整数) を報告し、 続いてオブジェクトを返します。コマンドレットが合計数を判別できない場 合、"Unknown total count" を返します。 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 の PositionalBinding 引数を使用 して、位置指定バインドを無効にできます。 PositionalBinding 引数は Windows PowerShell 3.0 で導入されました。 パラメーターが位置指定の場合、パラメーター名はオプションです。PowerShell は、名前のないパラメーター値を、関数コマンド内の名前のないパラメーター値 の順序または位置に従って関数パラメーターに関連付けます。 パラメーターが位置指定でない場合 ("名前付き")、コマンドにパラメーター名 (またはその名前の省略形やエイリアス) が必要です。 PositionalBinding が $true の場合、関数パラメーターは既定で位置指定です。 PowerShell は、関数で宣言された順序でパラメーターに位置番号を割り当てま す。 PositionalBinding が $false の場合、関数パラメーターは既定で位置指定では ありません。Parameter 属性の Position 引数がパラメーターで宣言されていな い限り、パラメーターが関数で使用されるときにパラメーター名 (またはエイリ アスや省略形) を含める必要があります。 Parameter 属性の Position 引数は、PositionalBinding の既定値よりも優先さ れます。Position 引数を使用して、パラメーターの位置値を指定できます。 Position 引数の詳細については、 about_Functions_Advanced_Parameters を参照してください。 注釈 SupportsTransactions 引数はアドバンス関数ではサポートされていません。 キーワード about_Functions_CmdletBinding_Attribute 関連項目 about_Functions about_Functions_Advanced about_Functions_Advanced_Methods about_Functions_Advanced_Parameters about_Functions_OutputTypeAttribute ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |