Register-ArgumentCompleter

構文

Register-ArgumentCompleter
        -CommandName <String[]>
        -ScriptBlock <ScriptBlock>
        [-Native]
        [<CommonParameters>]

Register-ArgumentCompleter
        [-CommandName <String[]>]
        -ParameterName <String>
        -ScriptBlock <ScriptBlock>
        [<CommonParameters>]

説明

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

このコマンドを CommandName パラメーターで呼び出し、ParameterName パラメーターまたはネイティブ パラメーター 指定しない場合、コマンドは Native パラメーターを指定したかのように実行されます。 これにより、引数 completer が PowerShell コマンド パラメーターに対して機能できなくなります。 PowerShell コマンドの引数 completer を登録する場合は、常に ParameterName パラメーターを指定します。

例

例 1: カスタム引数の完了を登録する

次の例では、Set-TimeZone コマンドレットの Id パラメーターの引数 completer を登録します。

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

最初のコマンドは、必要なパラメーターを受け取るスクリプト ブロックを作成します。これは、ユーザーが Tab 押したときに渡されます。詳細については、ScriptBlock パラメーターの説明を参照してください。

スクリプト ブロック内では、Id の使用可能な値は、Get-TimeZone コマンドレットを使用して取得されます。 各タイム ゾーンの Id プロパティは、Where-Object コマンドレットにパイプ処理されます。 Where-Object コマンドレットは、ユーザーが Tab を押す前に入力したテキストを表す、$wordToCompleteによって指定された値で始まらない ID除外します。フィルター処理された ID は、ForEach-Object コマンドレットにパイプ処理され、各値が引用符で囲まれ、スペースを含む値が処理されます。

2 番目のコマンドは、scriptblock、ParameterNameId、および CommandNameSet-TimeZoneを渡すことによって、引数の完了を登録します。

例 2: タブ補完値に詳細を追加する

次の例では、Stop-Service コマンドレットの Name パラメーターのタブ補完を上書きし、実行中のサービスのみを返します。

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    $services = Get-Service | Where-Object {
        $_.Status -eq 'Running' -and $_.Name -like "$wordToComplete*"
    }

    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList @(
            $_.Name          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

最初のコマンドは、必要なパラメーターを受け取るスクリプト ブロックを作成します。これは、ユーザーが Tab 押したときに渡されます。詳細については、ScriptBlock パラメーターの説明を参照してください。

スクリプト ブロック内で、最初のコマンドは、Where-Object コマンドレットを使用して実行中のすべてのサービスを取得します。 サービスは、ForEach-Object コマンドレットにパイプされます。 ForEach-Object コマンドレットは、新しい System.Management.Automation.CompletionResult オブジェクトを作成し、現在のサービスの名前 (パイプライン変数 $_.Nameで表されます) を設定します。

CompletionResult オブジェクトを使用すると、返される各値に追加の詳細を指定できます。

• completionText (String) - オートコンプリートの結果として使用するテキスト。 これは、コマンドに送信される値です。
• listItemText (文字列) - ユーザーが Ctrl +Space押したときなど、リストに表示されるテキスト。 PowerShell では、これを表示にのみ使用します。 選択した場合、コマンドには渡されません。
• resultType (CompletionResultType) - 完了結果の種類。
• toolTip (文字列) - オブジェクトに関する詳細を含むヒントのテキスト。 これは、Ctrl +Spaceキー押した後、ユーザーが項目を選択したときに表示されます。

例 3: カスタムネイティブ引数のコンプリートを登録する

Native パラメーターを使用して、ネイティブ コマンドのタブ補完を提供できます。 次の例では、dotnet コマンド ライン インターフェイス (CLI) のタブ補完を追加します。

$scriptblock = {
    param(
        $wordToComplete,
        $commandAst,
        $cursorPosition
    )

    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

最初のコマンドは、必要なパラメーターを受け取るスクリプト ブロックを作成します。これは、ユーザーが Tab 押したときに渡されます。詳細については、ScriptBlock パラメーターの説明を参照してください。

スクリプト ブロック内で、dotnet complete コマンドによってタブ補完が実行されます。 結果は、ForEach-Object コマンドレットにパイプ処理されます。このコマンドレット では、System.Management.Automation.CompletionResult クラスの新しい 静的メソッドを使用して、値ごとに CompletionResult オブジェクトを作成します。

パラメーター

-CommandName

-Native

-ParameterName

-ScriptBlock

入力

None

このコマンドレットにオブジェクトをパイプすることはできません。

出力

None

このコマンドレットは出力を返しません。

関連リンク

• about_Functions_Argument_Completion