Register-ArgumentCompleter
カスタム引数の完了を登録します。
構文
Register-ArgumentCompleter
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Register-ArgumentCompleter
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
説明
Register-ArgumentCompleter
コマンドレットは、カスタム引数の完了を登録します。 引数の完了機能を使用すると、指定した任意のコマンドに対して実行時に動的タブ補完を提供できます。
例
例 1: カスタム引数の完了を登録する
次の例では、Set-TimeZone
コマンドレットの Id パラメーターの引数 completer を登録します。
$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、 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,
$_.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) - ユーザーが Ctrl+Space を押したときなど、リストに表示されるテキスト。 これは表示にのみ使用され、選択した場合はコマンドに渡されません。
- resultType (CompletionResultType) - 完了結果の種類。
- toolTip (文字列) - オブジェクトに関する詳細が表示されるヒントのテキスト。 これは、ユーザーが Ctrl+Space キーを押した後項目を選択したときに表示されます。
最後のコマンドは、停止したサービスを引き続き手動で Stop-Service
コマンドレットに渡すことができることを示しています。 影響を受けるのはタブ補完だけです。
例 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($_, $_, 'ParameterValue', $_)
}
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock
最初のコマンドは、ユーザーが Tab を押したときに渡される必要なパラメーターを受け取るスクリプト ブロックを作成します。詳細については、 ScriptBlock パラメーターの説明を参照してください。
スクリプト ブロック内では、 dotnet complete
コマンドを使用してタブ補完を実行します。
結果は、ForEach-Object
コマンドレットにパイプ処理され、System.Management.Automation.CompletionResult クラスの new 静的メソッドを使用して、値ごとに新しい CompletionResult オブジェクトが作成されます。
パラメーター
-CommandName
コマンドの名前を配列として指定します。
型: | String[] |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Native
引数 completer が、PowerShell でパラメーター名を完了できないネイティブ コマンド用であることを示します。
型: | SwitchParameter |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-ParameterName
引数が完了するパラメーターの名前を指定します。 指定されたパラメーター名は、Write-Host
コマンドレットの ForegroundColor パラメーターなどの列挙値にすることはできません。
列挙型の詳細については、「 about_Enum」を参照してください。
型: | String |
配置: | Named |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-ScriptBlock
タブ補完を実行するために実行するコマンドを指定します。 指定するスクリプト ブロックは、入力を完了した値を返す必要があります。 スクリプト ブロックは、パイプライン (ForEach-Object
、 Where-Object
など) または別の適切なメソッドを使用して値の登録を解除する必要があります。 値の配列を返すと、PowerShell は配列全体をタブ補完値として処理します。
スクリプト ブロックは、次に示す順序で次のパラメーターを受け入れる必要があります。 PowerShell は位置によって値を渡すので、パラメーターの名前は重要ではありません。
$commandName
(位置 0) - このパラメーターは、スクリプト ブロックがタブ補完を提供するコマンドの名前に設定されます。$parameterName
(位置 1) - このパラメーターは、タブ補完が必要な値を持つパラメーターに設定されます。$wordToComplete
(位置 2) - このパラメーターは、ユーザーが Tab を押す前に指定した値に設定されます。スクリプト ブロックでは、この値を使用してタブ補完値を決定する必要があります。$commandAst
(位置 3) - このパラメーターは、現在の入力行の抽象構文ツリー (AST) に設定されます。 詳細については、「 Ast Class」を参照してください。$fakeBoundParameters
(位置 4) - このパラメーターは、ユーザーが Tab を押す前に、コマンドレットの$PSBoundParameters
を含むハッシュテーブルに設定されます。詳細については、about_Automatic_Variablesを参照してください。
Native パラメーターを指定する場合、スクリプト ブロックは指定した順序で次のパラメーターを受け取る必要があります。 PowerShell は位置によって値を渡すので、パラメーターの名前は重要ではありません。
$wordToComplete
(位置 0) - このパラメーターは、ユーザーが Tab を押す前に指定した値に設定されます。スクリプト ブロックでは、この値を使用してタブ補完値を決定する必要があります。$commandAst
(位置 1) - このパラメーターは、現在の入力行の抽象構文ツリー (AST) に設定されます。 詳細については、「 Ast Class」を参照してください。$cursorPosition
(位置 2) - このパラメーターは、ユーザーが Tab を押したときにカーソルの位置に設定されます。
パラメーター属性として ArgumentCompleter を指定することもできます。 詳細については、「about_Functions_Advanced_Parameters」を参照してください。
型: | ScriptBlock |
配置: | Named |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
入力
None
このコマンドレットにオブジェクトをパイプすることはできません。
出力
None
このコマンドレットは、出力を返しません。
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示