about_Functions_CmdletBindingAttribute

[アーティクル]
11/16/2015

適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0

トピック

簡単な説明

コンパイルされたコマンドレットと同様に関数を動作させる属性について説明します。

詳細な説明

CmdletBinding 属性は、C# で記述されコンパイルされたコマンドレットのように関数を動作させる関数の属性で、コマンドレットの機能へのアクセスを提供します。

Windows PowerShell® は、コンパイルされたコマンドレットのパラメーターをバインドするのと同じように、CmdletBinding 属性を持つ関数のパラメーターをバインドします。CmdletBinding 属性を持つ関数では、$PSCmdlet 自動変数は使えますが、$Args 変数は使えません。

CmdletBinding 属性を持つ関数では、不明なパラメーターと、一致する位置指定パラメーターを持たない位置指定引数があると、パラメーターのバインドが失敗します。

注記:コンパイルされたコマンドレットは、必須の Cmdlet 属性を使用します。この属性は、このトピックで説明する CmdletBinding 属性と似たものです。

構文

次の例は、CmdletBinding 属性のすべての省略可能な引数を指定する関数のフォーマットを示しています。例の後には、各引数の概要を示します。

        {
          [CmdletBinding(ConfirmImpact=<String>,
                     DefaultParameterSetName=<String>,
                     HelpURI=<URI>,
                     SupportsPaging=<Boolean>,
                     SupportsShouldProcess=<Boolean>,
                     PositionalBinding=<Boolean>)]

          Param ($Parameter1)
          Begin{}
          Process{}
          End{}
        }

ConfirmImpact

ConfirmImpact 引数では、ShouldProcess メソッドの呼び出しによって関数の操作をいつ確認するかを指定します。ConfirmImpact 引数がユーザー設定変数 $ConfirmPreference の値以上である場合にのみ、ShouldProcess メソッドの呼び出しによって確認プロンプトが表示されます。 (この引数の既定値は Medium です。)この引数は、SupportsShouldProcess 引数も指定されている場合にのみ指定してください。

確認要求の詳細については、MSDN ライブラリの「Requesting Confirmation」 (確認の要求) (https://go.microsoft.com/fwlink/?LinkId=136658) を参照してください。

DefaultParameterSetName

DefaultParameterSetName 引数では、どのパラメーターセットを使用してよいか判断できないときに Windows PowerShell が使用するパラメーターセットの名前を指定します。この問題を回避するには、各パラメーターセットの一意のパラメーターを必須パラメーターにします。

HelpURI

HelpURI 引数では、関数の説明をするオンラインバージョンのヘルプトピックのインターネットアドレス (Uniform Resource Identifier (URI)) を指定します。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" を返します。

Windows PowerShell には、返される総数値を取得し、総数値の正確さの目安を含めるヘルパーメソッド NewTotalCount があります。

以下の例の関数では、高度な関数にページングパラメーターのサポートを追加する方法を示します。

         function Get-Numbers
         {
             [CmdletBinding(SupportsPaging = $true)]
             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 です。PositionalBinding 引数の値を $False にして引き渡すと、位置によるバインドを無効にできます。

PositionalBinding 引数は Windows PowerShell 3.0 で導入されました。

位置指定パラメーターのパラメーター名は省略できます。Windows PowerShell は、関数コマンドの無名パラメーターの順序または位置に従って、無名パラメーターの値を関数パラメーターに関連付けます。

位置指定でない (名前のある) パラメーターの場合、コマンドにパラメーター名 (またはその略称かエイリアス) の記述が必要です。

PositionalBinding が $True の場合、関数のパラメーターは既定では位置指定パラメーターになります。Windows PowerShell は、関数で宣言されている順番に、パラメーターに位置番号を割り当てます。

PositionalBinding が $False の場合、関数のパラメーターは既定で位置指定ではありません。パラメーターで Parameter 属性の Position 引数を宣言しない限り、関数内でパラメーターを使うときには、パラメーター名 (またはその略称かエイリアス) を含める必要があります。

Parameter 属性の Position 引数は、PositionalBinding の既定値よりも優先されます。パラメーターの位置の値を指定するために、Position 引数を使うことができます。Position 引数の詳細については、about_Functions_Advanced_Parameters (https://go.microsoft.com/fwlink/?LinkID=135173) を参照してください。

注意事項

SupportsTransactions 引数は、高度な関数ではサポートされません。

キーワード

about_Functions_CmdletBinding_Attribute

about_Functions_CmdletBindingAttribute

トピック

簡単な説明

詳細な説明

注意事項

キーワード

関連項目

その他のリソース