about_Functions_CmdletBindingAttribute

簡単な説明

関数をコンパイル済みのコマンドレットのように機能させるための属性について説明します。

長い説明

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

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

属性を持つ関数では CmdletBinding 、位置パラメーターが一致しない不明なパラメーターおよび位置指定引数によって、パラメーターのバインドが失敗します。

注意

コンパイルされたコマンドレットは required 属性を使用し Cmdlet CmdletBinding ます。これは、このトピックで説明されている属性に似ています。

Syntax

次の例は、属性のすべての省略可能な引数を指定する関数の形式を示して CmdletBinding います。 各引数の簡単な説明を次に示します。

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

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

ConfirmImpact

Confirmimpact 引数は、メソッドの 呼び出しによって関数のアクションを確認するタイミングを指定します。 値を指定する メソッドを 呼び出すと、 confirmimpact 引数がユーザー設定変数の値以上の場合にのみ、確認プロンプトが表示され $ConfirmPreference ます。 (引数の既定値は Medium です)。この引数は、 supports指定 の引数も指定されている場合にのみ指定します。

確認要求の詳細については、「 確認の要求」を参照してください。

DefaultParameterSetName

DefaultParameterSetName 引数には、使用するパラメーターセットを決定できない場合に PowerShell が使用するパラメーターセットの名前を指定します。 この問題を回避するには、各パラメーターの unique パラメーターに必須パラメーターを設定します。

HelpURI

HelpURI 引数 は、関数について説明するヘルプ トピックのオンライン バージョンのインターネット アドレスを指定します。 HelpURI 引数の 値は 、"http" または "https" で始まる必要があります。

HelpURI 引数 の値は、関数に対して返される CommandInfo オブジェクトの HelpURI プロパティ Get-Command の値に使用されます。

ただし、ヘルプ ファイルがコンピューターにインストールされ、ヘルプ ファイルの RelatedLinks セクションの最初のリンクの値が URI である場合、またはコメント ベースのヘルプの最初のディレクティブの値が URI の場合、ヘルプ ファイルの URI が関数の .Link HelpUri プロパティの値として使用されます。

コマンドレット Get-Help、HelpURI プロパティの値を使用して、 の Online パラメーターがコマンドで指定されている場合に、オンライン バージョンの関数ヘルプ トピック Get-Help を検索します。

SupportsPaging

SupportsPaging 引数は**、First、Skip、**および IncludeTotalCount パラメーターを関数に追加します。 これらのパラメーターを使用すると、ユーザーは非常に大きな結果セットから出力を選択できます。 この引数は、SQL データベースなどのデータ選択をサポートする大規模なデータ ストアからデータを返すコマンドレットと関数用に設計されています。

この引数は、3.0 Windows PowerShellで導入されました。

  • First: 最初の 'n' オブジェクトのみを取得します。
  • Skip: 最初の 'n' オブジェクトを無視し、残りのオブジェクトを取得します。
  • IncludeTotalCount: データ セット内のオブジェクトの数 (整数) とそれに続くオブジェクトを報告します。 コマンドレットで合計カウントを確認できない場合は、"不明な合計カウント" が返されます。

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 引数 は、3.0 Windows PowerShellで導入されています。

パラメーターが位置指定の場合、パラメーター名は省略可能です。 PowerShell は、関数コマンドの名前のないパラメーター値の順序または位置に従って、名前のないパラメーター値を関数パラメーターに関連付ける。

パラメーターが位置指定 ("名前付き" である) 場合は、パラメーター名 (または名前の省略形または別名) がコマンドに必要です。

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

PositionalBinding が の場合 $False 、関数パラメーターは既定では位置指定されません。 パラメーター 属性 の Position 引数がパラメーターで宣言されていない限り、パラメーター名 (またはエイリアスまたは省略形) は、パラメーターが関数で使用される場合に含める必要があります。

Parameter 属性Position 引数は**、PositionBinding** の既定値よりも優先されます。 Position 引数を 使用して 、パラメーターの位置の値を指定できます。 Position 引数の詳細については、「 を参照 about_Functions_Advanced_Parameters。

メモ

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

Keywords

about_Functions_CmdletBinding_Attribute

こちらもご覧ください

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute