about_Functions_Argument_Completion

簡単な説明

引数補完は、ヒントを提供し、検出を可能にし、引数値の入力入力を高速化する PowerShell の機能です。

長い説明

この記事では、PowerShell 関数の引数コンプリートを実装するさまざまな方法について説明します。 引数の完了子は、パラメーターに使用できる値を提供します。 使用可能な値は、ユーザーがパラメーター名の後に Tab キーを押すと実行時に計算されます。 パラメーターの引数コンプリートを定義するには、いくつかの方法があります。

注意

Tab は、Windows の既定のキー バインドです。 このキーバインドは、PSReadLine モジュールまたは PowerShell をホストしているアプリケーションによって変更できます。 キーバインドは、Windows 以外のプラットフォームでは異なります。 詳細については、「about_PSReadLine」を参照してください。

ValidateSet 属性

ValidateSet 属性は、パラメーターまたは変数の有効な値のセットを指定し、タブ補完を有効にします。 パラメーターまたは変数の値がセット内の値と一致しない場合、PowerShell はエラーを生成します。 次の例では、 Fruit パラメーターの値には Apple、 Banana、 Pear のみを指定できます。

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet('Apple', 'Banana', 'Pear')]
    [string[]]
    $Fruit
)

次の例では、変数 $flavor の値は Chocolate、 Strawberry、または Vanilla である必要があります。 属性は ValidateSet 、パラメーターだけでなく、任意の変数で使用できます。

[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'

検証は、スクリプト内でも変数が割り当てられるたびに発生します。

Param(
    [ValidateSet('hello', 'world')]
    [string]$Message
)

$Message = 'bye'

この例では、実行時に次のエラーが返されます。

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

タブ展開の詳細については、「 about_Tab_Expansion」を参照してください。

クラスを使用した動的な ValidateSet 値

クラスを使用すると、実行時に ValidateSet の値を動的に生成できます。 次の例では、使用可能なサウンド ファイルの 3 つのファイルシステム パスをチェックする SoundNames という名前のクラスを使用して、変数$Soundの有効な値が生成されます。

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
                      '/Library/Sounds',
                      '~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

[SoundNames]その後、 クラスは動的な ValidateSet 値として次のように実装されます。

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

注意

クラスは IValidateSetValuesGenerator PowerShell 6.0 で導入されました。

ArgumentCompletions 属性

ArgumentCompletions 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 ArgumentCompletions 属性は、タブ補完が必要なパラメーターごとに定義する必要があります。 ArgumentCompletions 属性は ValidateSet に似ています。 どちらの属性も、ユーザーがパラメーター名の後に Tab キー を押したときに表示される値の一覧を取得します。 ただし、 ValidateSet とは異なり、値は検証されず、提案に似ています。 したがって、ユーザーは、リスト内の値だけでなく、任意の値を指定できます。

ArgumentCompletions 属性を ArgumentCompleter 属性と混同しないでください。この属性には、オプションを定義するためのスクリプトブロックが必要です。 指定した値を使用できます

構文は次のとおりです。

function Test-ArgumentCompletions {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ArgumentCompletions('Fruits', 'Vegetables')]
        $Type,

        [Parameter()]
        [ArgumentCompletions('Apple', 'Banana', 'Orange')]
        $Fruit,

        [Parameter()]
        [ArgumentCompletions('Tomato', 'Corn', 'Squash')]
        $Vegetable
    )
}

各パラメーターには、タブ補完を有効にするために ArgumentCompletions 属性にオプションの一覧が表示されます。

この属性は、PowerShell 6.0 で導入されました。

ArgumentCompleter 属性

ArgumentCompleter 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 ArgumentCompleter 属性は、タブ補完が必要なパラメーターごとに定義する必要があります。

ArgumentCompleter 属性を追加するには、値を決定するスクリプト ブロックを定義する必要があります。 スクリプト ブロックは、次に示す順序で次のパラメーターを受け取る必要があります。 パラメーターの名前は、値が位置指定されるため、重要ではありません。

構文は次のとおりです。

function MyArgumentCompleter {
    Param(
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )
            # Perform calculation of tab completed values here.
        } )]
        $ParamName
    )
}

ArgumentCompleter スクリプト ブロック

スクリプト ブロック パラメーターは、次の値に設定されます。

• $commandName (位置 0) - このパラメーターは、スクリプト ブロックがタブ補完を提供するコマンドの名前に設定されます。
• $parameterName (位置 1) - このパラメーターは、タブ補完を必要とする値を持つパラメーターに設定されます。
• $wordToComplete (位置 2) - このパラメーターは、 ユーザーが Tab キーを押す前に指定した値に設定されます。スクリプト ブロックでは、この値を使用してタブ補完値を決定する必要があります。
• $commandAst (位置 3) - このパラメーターは、現在の入力行の抽象構文ツリー (AST) に設定されます。 詳細については、 AST 型のドキュメントを参照してください。
• $fakeBoundParameters(位置 4) - このパラメーターは、ユーザーが Tab キーを押す$PSBoundParameters前に、 コマンドレットの を含むハッシュテーブルに設定されます。詳細については、「about_Automatic_Variables」を参照してください。

ArgumentCompleter スクリプト ブロックは、パイプライン (、、または別の適切なメソッド) ForEach-ObjectWhere-Objectを使用して値の登録を解除する必要があります。 値の配列を返すと、PowerShell は配列全体を 1 つの タブ補完値として扱います。

次の例では、タブ補完を Value パラメーターに追加します。 Value パラメーターのみを指定すると、Value に使用できるすべての値または引数が表示されます。 Type パラメーターを指定すると、Value パラメーターには、その型に使用できる値のみが表示されます。

さらに、 演算子は -like 、ユーザーが次のコマンドを入力し、 Tab 入力候補を使用する場合、 Apple のみが返されるようにします。

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Tomato', 'Squash', 'Corn')
    }

    if ($fakeBoundParameters.ContainsKey('Type')) {
        $possibleValues[$fakeBoundParameters.Type] | Where-Object {
            $_ -like "$wordToComplete*"
        }
    } else {
        $possibleValues.Values | ForEach-Object {$_}
    }
}

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,

        [Parameter(Mandatory=$true)]
        [ArgumentCompleter({ MyArgumentCompleter @args })]
        $Value
      )
}

Register-ArgumentCompleter

コマンドレットは Register-ArgumentCompleter 、カスタム引数 completer を登録します。 引数の完了機能を使用すると、指定した任意のコマンドに対して実行時に動的なタブ補完を提供できます。

詳細については、「Register-ArgumentCompleter」を参照してください。

こちらもご覧ください

• about_Functions_Advanced_Parameters
• about_Tab_Expansion
• Register-ArgumentCompleter