通过

Register-ArgumentCompleter

  • 参考
模块:
Microsoft.PowerShell.Core

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

语法

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

说明

cmdlet Register-ArgumentCompleter 注册自定义参数完成程序。 参数补全器允许你在运行时为指定的任何命令提供动态选项卡补全。

示例

示例 1：注册自定义参数完成器

以下示例为 cmdlet 的 Set-TimeZoneId 参数注册一个参数完成程序。

$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 会通过管道传递到 For-EachObject cmdlet，该 cmdlet 将每个值括在引号中。

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

示例 2：向选项卡完成值添加详细信息

以下示例覆盖 cmdlet 的 Name 参数的 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。 cmdlet ForEach-Object 创建新的 System.Management.Automation.CompletionResult 对象，并使用管道变量 $_.Name) 表示的当前服务 (的名称填充该对象。

CompletionResult 对象允许你为每个返回的值提供其他详细信息：

  • completionText (字符串) - 要用作自动完成结果的文本。 这是发送到 命令的值。
  • listItemText (字符串) - 要显示在列表中的文本，例如当用户按 Ctrl+空格时。 这仅用于显示，并且不会在选中时传递给 命令。
  • resultType (CompletionResultType) - 完成结果的类型。
  • 工具提示 (字符串) - 工具提示的文本，其中包含要显示有关对象的详细信息。 当用户在按 Ctrl+空格键后选择项时，这可见。

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

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

可以使用 Native 参数为本机命令提供制表符补全。 以下示例为 dotnet 命令行接口 (CLI) 添加 tab-completion。

注意

命令 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 ，命令用于执行选项卡补全。 结果通过管道传递给 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-HostForegroundColor 参数。

有关枚举的详细信息，请参阅 about_Enum。

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

指定要运行以执行选项卡补全的命令。 提供的脚本块应返回完成输入的值。 脚本块必须使用管道 (ForEach-Object、 Where-Object等 ) 或其他合适的方法展开值。 返回值数组会导致 PowerShell 将整个数组视为 一个 选项卡完成值。

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

  • $commandName (位置 0) - 此参数设置为脚本块为其提供选项卡补全的命令的名称。
  • $parameterName (位置 1) - 此参数设置为其值需要选项卡完成的参数。
  • $wordToComplete (位置 2) - 此参数设置为用户按下 Tab 之前提供的值。脚本块应使用此值来确定选项卡完成值。
  • $commandAst (位置 3) - 此参数设置为当前输入行的抽象语法树 (AST) 。 有关详细信息，请参阅 Ast 类。
  • $fakeBoundParameters (位置 4) - 在用户按 Tab 之前，此参数设置为包含 $PSBoundParameters cmdlet 的 哈希表。有关详细信息，请参阅 about_Automatic_Variables。

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

  • $wordToComplete (位置 0) - 此参数设置为用户按下 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 不返回任何输出。