Register-ArgumentCompleter

  • 参考
模块:
Microsoft.PowerShell.Core

注册自定义参数完成程序。

语法

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

说明

Register-ArgumentCompleter cmdlet 会注册自定义参数完成程序。 通过参数完成程序，可以在运行时为指定的任何命令提供动态 Tab 完成。

示例

示例 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 时传入的必需参数。有关详细信息，请参阅 ScriptBlock 参数说明。

在脚本块中，使用 Get-TimeZone cmdlet 检索 Id 的可用值。 每个时区的 Id 属性通过管道传递给 Where-Object cmdlet。 Where-Object cmdlet 会筛选出任何不以 $wordToComplete 提供的值开头的 ID，这表示用户在 按下 Tab 之前键入的文本。筛选的 ID 通过管道传递给 ForEach-Object cmdlet，如果值包含空格，cmdlet 会将每个值括在引号中。

第二个命令通过传递 scriptblock、ParameterNameId 和 CommandNameSet-TimeZone 来注册参数完成程序。

示例 2：向 Tab 完成值添加详细信息

以下示例覆盖 Stop-Service cmdlet 的 Name 参数的 Tab 完成，并且仅返回正在运行的服务。

$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（字符串）- 在列表中显示的文本，例如当用户按下 Ctrl+Space 时。 这仅用于显示，选择时不会传递给命令。
  • resultType (CompletionResultType) - 完成结果的类型。
  • toolTip（字符串） - 要显示有关对象的详细信息的工具提示的文本。 当用户在按 Ctrl+Space 后选择项目时，此内容可见。

最后一个命令演示停止的服务仍可手动传递到 Stop-Service cmdlet。 Tab 完成是唯一受影响的方面。

示例 3：注册自定义本机参数完成程序

可以使用 Native 参数为本机命令提供 Tab 完成。 以下示例为 dotnet 命令行接口 (CLI) 添加 Tab 完成。

注意

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 命令用于执行 Tab 完成。 结果通过管道传递给 ForEach-Object cmdlet，该 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

指定其参数正在完成的参数的名称。 指定的参数名称不能是枚举值，例如 Write-Host cmdlet 的 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 将整个数组视为一个 Tab 完成值。

脚本块必须按照下面指定的顺序采用以下参数。 参数的名称并不重要，因为 PowerShell 按位置传入值。

  • $commandName（位置 0）- 此参数设置为脚本块提供 Tab 完成的命令的名称。
  • $parameterName（位置 1）- 此参数设置为其值需要 Tab 完成的参数。
  • $wordToComplete（位置 2）- 此参数设置为用户在按下 Tab 之前提供的值。脚本块应使用此值来确定 Tab 完成值。
  • $commandAst（位置 3）- 此参数设置为当前输入行的抽象语法树 (AST)。 有关详细信息，请参阅 Ast 类。
  • $fakeBoundParameters（位置 4）- 此参数设置为在用户按下 Tab 之前包含 cmdlet 的 $PSBoundParameters 的哈希表。有关详细信息，请参阅 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 不返回任何输出。