Register-ArgumentCompleter

  • リファレンス
モジュール:
Microsoft.PowerShell.Core

カスタム引数 completer を登録します。

構文

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

説明

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

例

例 1: カスタム引数 completer を登録する

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

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

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock

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

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

2 番目のコマンドは、scriptblock、ParameterNameID、および CommandName を渡すことによって、引数 completer を登録しますSet-TimeZone。

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

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

$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,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
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 (String) - ユーザーが CtrlSpaceキー+を押したときなど、リストに表示されるテキスト。 これは表示のみに使用され、選択した場合はコマンドに渡されません。
  • resultType (CompletionResultType) - 完了結果の型。
  • toolTip (文字列) - オブジェクトに関する詳細が表示されるツールヒントのテキスト。 これは、Ctrl Space キー+を押した後にユーザーが項目を選択すると表示されます。

最後のコマンドは、停止したサービスをコマンドレットに手動 Stop-Service で渡すことができることを示しています。 影響を受ける唯一の側面はタブ補完です。

例 3: カスタムネイティブ引数 completer を登録する

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

注意

この dotnet complete コマンドは、バージョン 2.0 以降の dotnet cli でのみ使用できます。

$scriptblock = {
    param($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

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

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

パラメーター

-CommandName

コマンドの名前を配列として指定します。

Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Native

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

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ParameterName

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

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

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ScriptBlock

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

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

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

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

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

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

Type:ScriptBlock
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

入力

None

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

出力

None

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