Register-ArgumentCompleter

リファレンス

モジュール:: Microsoft.PowerShell.Core

カスタム引数の完了を登録します。

構文

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

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

説明

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

このコマンドを CommandName パラメーターで呼び出し、 ParameterName または Native パラメーターを指定しない場合、コマンドは 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 コマンドレットは、$wordToCompleteによって指定された値で始まらない ID を除外します。これは、ユーザーが Tab を押す前に入力したテキストを表します。フィルター処理された ID は、ForEach-Object コマンドレットにパイプ処理され、各値が引用符で囲まれ、スペースを含む値が処理されます。

2 番目のコマンドは、scriptblock、 ParameterName Id 、および CommandName Set-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

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

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

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

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

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

Note

dotnet complete コマンドは、バージョン 2.0 以降の 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

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

パラメーター

-CommandName

引数の完了を登録する 1 つ以上のコマンドの名前を指定します。このパラメーターは、ネイティブコマンドでは必須です。

このパラメーターを ParameterName または Native パラメーターなしで指定すると、コマンドは Native パラメーターを指定したかのように動作します。 PowerShell コマンドの引数の完了を登録するときは、常に ParameterName パラメーターを指定します。

このパラメーターを指定しない場合、PowerShell はすべての PowerShell コマンドで、指定した ParameterName の引数の完了を登録します。

型:	String[]
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-Native

引数 completer が、PowerShell でパラメーター名を完了できないネイティブコマンド用であることを示します。

型:	SwitchParameter
配置:	Named
規定値:	None
必須:	False
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ParameterName

引数 completer が適用されるパラメーターの名前を指定します。指定したパラメーターの型は、Write-Host コマンドレットの ForegroundColor パラメーターなどの列挙型にすることはできません。

列挙型の詳細については、「 about_Enum」を参照してください。

PowerShell コマンドの引数 completer を登録するときは、常にこのパラメーターを指定します。 ParameterName または Native パラメーターを指定せずに CommandName パラメーターを指定すると、コマンドは Native パラメーターを指定したかのように動作します。

型:	String
配置:	Named
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

-ScriptBlock

タブ補完を実行するために実行するコマンドを指定します。指定するスクリプトブロックは、入力を完了した値を返す必要があります。スクリプトブロックは、パイプライン (ForEach-Object、 Where-Objectなど) または別の適切なメソッドを使用して値の登録を解除する必要があります。値の配列を返すと、PowerShell は配列全体をタブ補完値として処理します。

スクリプトブロックは、ユーザーエクスペリエンスを向上させるために、値ごとに System.Management.Automation.CompletionResult オブジェクトを返すこともできます。 CompletionResult オブジェクトを返すと、ユーザーが Ctrl+Space を押したときに表示されるツールヒントとカスタムリストエントリを定義して、使用可能な入力候補の一覧を表示できます。

スクリプトブロックは、次に示す順序で次のパラメーターを受け入れる必要があります。 PowerShell は位置によって値を渡すので、パラメーターの名前は重要ではありません。

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

Native パラメーターを指定する場合、スクリプトブロックは指定した順序で次のパラメーターを受け取る必要があります。 PowerShell は位置によって値を渡すので、パラメーターの名前は重要ではありません。

$wordToComplete (位置 0、 文字列) - このパラメーターは、ユーザーが Tab を押す前に指定した値に設定されます。スクリプトブロックでは、この値を使用してタブ補完値を決定する必要があります。
$commandAst (位置 1、 CommandAst) - このパラメーターは、現在の入力行の抽象構文ツリー (AST) に設定されます。詳細については、「 CommandAst クラスを参照してください。
$cursorPosition (位置 2、 Int32) - このパラメーターは、ユーザーが Tab を押したときにカーソルの位置に設定されます。

パラメーター属性として ArgumentCompleter を指定することもできます。詳細については、「about_Functions_Advanced_Parameters」を参照してください。

型:	ScriptBlock
配置:	Named
規定値:	None
必須:	True
パイプライン入力を受け取る:	False
ワイルドカード文字を受け取る:	False

入力

None

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

出力

None

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

about_Functions_Argument_Completion

次の方法で共有

Register-ArgumentCompleter

構文

説明

例

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

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

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

パラメーター

-CommandName

-Native

-ParameterName

-ScriptBlock

入力

出力

その他のリソース

次の方法で共有

Register-ArgumentCompleter

構文

説明

例

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

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

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

パラメーター

-CommandName

-Native

-ParameterName

-ScriptBlock

入力

出力

関連リンク

その他のリソース