通过

Register-ArgumentCompleter

  • 参考
模块:
Microsoft.PowerShell.Core

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

语法

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

说明

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

示例

示例 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、 ParameterName “Id”和 CommandNameSet-TimeZone 来注册参数完成程序。

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

以下示例覆盖 cmdlet 的 Name 参数的 Tab 自动补全， Stop-Service 并仅返回正在运行的服务。

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" }
    $services | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_,
            $_,
            "ParameterValue",
            $_
    }
}
Register-ArgumentCompleter -CommandName dotnet -Native -ScriptBlock $s

第一个命令创建一个脚本块，该脚本块采用用户按下 <TAB>时传入的必需参数。 有关详细信息，请参阅 ScriptBlock 参数说明。

在脚本块中，第一个命令使用 Where-Object cmdlet 检索所有正在运行的服务。 服务通过管道传递给 ForEach-Object cmdlet。 cmdlet ForEach-Object 创建一个新的 [System.Management.Automation.CompletionResult] 对象，并使用管道变量 $_) 表示的当前服务 (的值填充该对象。

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

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

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

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

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

注意

命令 dotnet complete 仅在 dotnet cli 2.0 及更高版本中可用。

$scriptblock = {
     param($commandName, $wordToComplete, $cursorPosition)
         dotnet complete --position $cursorPosition "$wordToComplete" | 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-HostForegroundColor 参数。

有关枚举的详细信息，请参阅 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 类。
  • $fakeBoundParameter (位置 4) - 在用户按下 <TAB>之前，此参数设置为包含 $PSBoundParameters cmdlet 的 的哈希表。 有关详细信息，请参阅 about_Automatic_Variables。

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

  • $commandName (位置 0) - 此参数设置为脚本块为其提供制表符补全的命令的名称。
  • $wordToComplete (位置 1) - 此参数设置为用户在按下 <TAB>之前提供的值。 脚本块应使用此值来确定 Tab 自动补全值。
  • $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 不返回任何输出。