about_Functions_Argument_Completion

  • [アーティクル]

簡単な説明

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

詳細な説明

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

Note

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
)

Note

このクラスは IValidateSetValuesGenerator 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-Object、Where-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 = @('Onion', 'Carrot', 'Lettuce')
    }

    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 、カスタム引数の完了を登録します。 引数の完了機能を使用すると、指定した任意のコマンドに対して実行時に動的タブ補完を提供できます。

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

関連項目