about_Functions_CmdletBindingAttribute

簡単な説明

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

長い説明

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

CmdletBinding 属性を使用すると、PowerShell によって共通パラメーターが自動的に追加されます。共通パラメーターと同じ名前を使用するパラメーターは作成できません。詳細については、about_CommonParametersを参照してください。

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

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

手記

コンパイルされたコマンドレットでは、必要な 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 基本設定変数の値以上の場合にのみ、確認プロンプトが表示されます。 (引数の既定値は Mediumです)。この引数は、SupportsShouldProcess 引数も指定されている場合にのみ指定します。

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

DefaultParameterSetName

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

HelpUri

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

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

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

Get-Help コマンドレットは、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

位置指定バインド 引数は、関数内のパラメーターが既定で位置指定されているかどうかを決定します。既定値は $trueです。位置バインディングを無効にするには、位置バインド 引数と $false の値を使用できます。

位置指定バインドの 引数は、Windows PowerShell 3.0 で導入されています。

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

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

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

位置指定バインド が $falseされている場合、関数パラメーターは既定では位置指定されません。パラメーターで Parameter 属性の Position 引数を宣言しない限り、パラメーター名 (または別名または省略形) を関数で使用する場合は、パラメーター名を含めなければなりません。

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

注記

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

キーワード

about_Functions_CmdletBinding_Attribute

こちらも参照ください

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-02-05