Register-Argument
Completer
Registers a custom argument completer.
Syntax
Register-Argument Completer
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Register-Argument Completer
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
Description
The
Register-ArgumentCompleter
cmdlet registers a custom argument completer. An argument
completer allows you to provide dynamic tab completion, at run time for any command that you
specify.
Examples
Example 1: Register a custom argument completer
The following example registers an argument completer for the
Id
parameter of the
Set-TimeZone
cmdlet.
$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
The first command creates a script block which takes the required parameters which are passed in when the user presses Tab . For more information, see the ScriptBlock parameter description.
Within the script block, the available values for
Id
are retrieved using the
Get-TimeZone
cmdlet. The
Id
property for each Time Zone is piped to the
Where-Object
cmdlet. The
Where-Object
cmdlet filters out any ids that do not start with the value provided by
$wordToComplete
, which represents the text the user typed before they pressed
Tab
. The
filtered ids are piped to the
ForEach-Object
cmdlet which encloses each value in quotes, should
the value contain spaces.
The second command registers the argument completer by passing the scriptblock, the
ParameterName
Id
and the
CommandName
Set-TimeZone
.
Example 2: Add details to your tab completion values
The following example overwrites tab completion for the
Name
parameter of the
Stop-Service
cmdlet and only returns running services.
$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
The first command creates a script block which takes the required parameters which are passed in when the user presses Tab . For more information, see the ScriptBlock parameter description.
Within the script block, the first command retrieves all running services using the
Where-Object
cmdlet. The services are piped to the
ForEach-Object
cmdlet. The
ForEach-Object
cmdlet creates
a new
System.Management.Automation.CompletionResult
object
and populates it with the name of the current service (represented by the pipeline variable
$_.Name
).
The CompletionResult object allows you to provide additional details to each returned value:
- completionText (String) - The text to be used as the auto completion result. This is the value sent to the command.
- listItemText (String) - The text to be displayed in a list, such as when the user presses Ctrl + Space . This is used for display only and is not passed to the command when selected.
- resultType ( CompletionResultType ) - The type of completion result.
- toolTip (String) - The text for the tooltip with details to be displayed about the object. This is visible when the user selects an item after pressing Ctrl + Space .
The last command demonstrates that stopped services can still be passed in manually to the
Stop-Service
cmdlet. The tab completion is the only aspect affected.
Example 3: Register a custom Native argument completer
You can use the
Native
parameter to provide tab-completion for a native command. The following
example adds tab-completion for the
dotnet
Command Line Interface (CLI).
Note
The
dotnet complete
command is only available in version 2.0 and greater of the 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
The first command creates a script block which takes the required parameters which are passed in when the user presses Tab . For more information, see the ScriptBlock parameter description.
Within the script block, the
dotnet complete
command is used to perform the tab completion.
The results are piped to the
ForEach-Object
cmdlet which use the
new
static method of the
System.Management.Automation.CompletionResult
class
to create a new
CompletionResult
object for each value.
Parameters
-CommandName
Specifies the name of the commands as an array.
Type: | String [ ] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Native
Indicates that the argument completer is for a native command where PowerShell cannot complete parameter names.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ParameterName
Specifies the name of the parameter whose argument is being completed. The parameter name specified
cannot be an enumerated value, such as the
ForegroundColor
parameter of the
Write-Host
cmdlet.
For more information on enums, see about_Enum .
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ScriptBlock
Specifies the commands to run to perform tab completion. The script block you provide should return
the values that complete the input. The script block must unroll the values using the pipeline
(
ForEach-Object
,
Where-Object
, etc.), or another suitable method. Returning an array of values
causes PowerShell to treat the entire array as
one
tab completion value.
The script block must accept the following parameters in the order specified below. The names of the parameters aren't important because PowerShell passes in the values by position.
-
$commandName
(Position 0) - This parameter is set to the name of the command for which the script block is providing tab completion. -
$parameterName
(Position 1) - This parameter is set to the parameter whose value requires tab completion. -
$wordToComplete
(Position 2) - This parameter is set to value the user has provided before they pressed Tab . Your script block should use this value to determine tab completion values. -
$commandAst
(Position 3) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see Ast Class . -
$fakeBoundParameters
(Position 4) - This parameter is set to a hashtable containing the$PSBoundParameters
for the cmdlet, before the user pressed Tab . For more information, see about_Automatic_Variables .
When you specify the Native parameter, the script block must take the following parameters in the specified order. The names of the parameters aren't important because PowerShell passes in the values by position.
-
$wordToComplete
(Position 0) - This parameter is set to value the user has provided before they pressed Tab . Your script block should use this value to determine tab completion values. -
$commandAst
(Position 1) - This parameter is set to the Abstract Syntax Tree (AST) for the current input line. For more information, see Ast Class . -
$cursorPosition
(Position 2) - This parameter is set to the position of the cursor when the user pressed Tab .
You can also provide an ArgumentCompleter as a parameter attribute. For more information, see about_Functions_Advanced_Parameters .
Type: | ScriptBlock |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
None
You can't pipe objects to this cmdlet.
Outputs
None
This cmdlet returns no output.