Register-ArgumentCompleter
注册自定义参数完成程序。
语法
Register-ArgumentCompleter
-CommandName <String[]>
-ScriptBlock <ScriptBlock>
[-Native]
[<CommonParameters>]
Register-ArgumentCompleter
[-CommandName <String[]>]
-ParameterName <String>
-ScriptBlock <ScriptBlock>
[<CommonParameters>]
说明
Register-ArgumentCompleter
cmdlet 注册自定义参数完成程序。 通过参数完成器,可以在运行时为指定的任何命令提供动态选项卡完成。
示例
示例 1:注册自定义参数完成程序
以下示例为 Set-TimeZone
cmdlet 的 Id 参数注册参数完成程序。
$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 tab时传入的必需参数。有关详细信息,请参阅 ScriptBlock 参数说明。
在脚本块中,使用 Get-TimeZone
cmdlet 检索 ID 的可用值。 每个时区的 Id 属性通过管道传递给 Where-Object
cmdlet。
Where-Object
cmdlet 会筛选出不以 $wordToComplete
提供的值开头的任何 ID,该 ID 表示用户在按 Tab Tab之前键入的文本。筛选的 ID 通过管道传递给将每个值括在引号中的 ForEach-Object
cmdlet,如果值包含空格。
第二个命令通过传递 scriptblock、ParameterNameId 和 CommandNameSet-TimeZone
来注册参数完成程序。
示例 2:向选项卡完成值添加详细信息
以下示例覆盖 Stop-Service
cmdlet 的 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 tab时传入的必需参数。有关详细信息,请参阅 ScriptBlock 参数说明。
在脚本块中,第一个命令使用 Where-Object
cmdlet 检索所有正在运行的服务。 服务通过管道传递给 ForEach-Object
cmdlet。
ForEach-Object
cmdlet 创建新的 System.Management.Automation.CompletionResult 对象,并使用当前服务的名称填充它(由管道变量 $_.Name
表示)。
CompletionResult 对象允许向每个返回的值提供其他详细信息:
- completionText (字符串) - 要用作自动完成结果的文本。 这是发送到命令的值。
- listItemText (String) - 列表中要显示的文本,例如当用户按下 Ctrl +空格时。 这仅用于显示,未在选中时传递给命令。
- resultType (CompletionResultType) - 完成结果的类型。
- 工具提示 (字符串) - 要显示有关对象的详细信息的工具提示的文本。 当用户 在按 Ctrl+空格后选择项目时,这可见。
最后一个命令演示停止的服务仍可手动传递到 Stop-Service
cmdlet。 选项卡完成是受影响的唯一方面。
示例 3:注册自定义本机参数完成程序
可以使用 Native 参数为本机命令提供 Tab 补全。 以下示例为 dotnet
命令行接口 (CLI) 添加制表符补全。
注意
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 tab时传入的必需参数。有关详细信息,请参阅 ScriptBlock 参数说明。
在脚本块中,dotnet complete
命令用于执行选项卡完成。
结果通过管道传递给 ForEach-Object
cmdlet,该 cmdlet 使用 System.Management.Automation.CompletionResult 类的新 静态方法为每个值创建新的 CompletionResult 对象。
参数
-CommandName
将命令的名称指定为数组。
类型: | String[] |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Native
指示参数完成程序适用于 PowerShell 无法完成参数名称的本机命令。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ParameterName
指定其参数正在完成的参数的名称。 指定的参数名称不能是枚举值,例如 Write-Host
cmdlet 的 ForegroundColor 参数。
有关枚举的详细信息,请参阅 about_Enum。
类型: | String |
Position: | Named |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-ScriptBlock
指定要运行的命令以执行选项卡完成。 提供的脚本块应返回完成输入的值。 脚本块必须使用管道(ForEach-Object
、Where-Object
等)或其他合适的方法取消注册值。 返回值数组会导致 PowerShell 将整个数组视为 一个 选项卡完成值。
脚本块必须接受以下参数,其顺序如下。 参数的名称并不重要,因为 PowerShell 按位置传入值。
-
$commandName
(位置 0) - 此参数设置为脚本块提供选项卡完成的命令的名称。 -
$parameterName
(位置 1) - 此参数设置为其值需要选项卡完成的参数。 -
$wordToComplete
(位置 2) - 此参数设置为用户在按下 Tab tab之前提供的值。脚本块应使用此值来确定选项卡完成值。 -
$commandAst
(位置 3) - 此参数设置为当前输入行的抽象语法树(AST)。 有关详细信息,请参阅 Ast 类。 -
$fakeBoundParameters
(位置 4) - 此参数设置为包含 cmdlet$PSBoundParameters
的哈希表,然后用户按下 Tab Tab。有关详细信息,请参阅 about_Automatic_Variables。
指定 Native 参数时,脚本块必须按指定顺序采用以下参数。 参数的名称并不重要,因为 PowerShell 按位置传入值。
-
$wordToComplete
(位置 0) - 此参数设置为用户在按下 tab 之前提供的值。脚本块应使用此值来确定选项卡完成值。 -
$commandAst
(位置 1) - 此参数设置为当前输入行的抽象语法树(AST)。 有关详细信息,请参阅 Ast 类。 -
$cursorPosition
(位置 2) - 当用户按下 Tab Tab时,此参数将设置为光标的位置。
还可以提供 ArgumentCompleter 作为参数属性。 有关详细信息,请参阅 about_Functions_Advanced_Parameters。
类型: | ScriptBlock |
Position: | Named |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
输入
None
不能通过管道将对象传递给此 cmdlet。
输出
None
此 cmdlet 不返回任何输出。