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