使用 PowerShell ArgumentCompleters 进行动态 Tab 补全

大多数人利用的一个方便的 PowerShell 功能是参数值选项卡完成。参数值 PowerShell Tab 自动补全功能允许您通过 Tab 键浏览可传递给 PowerShell 命令的可用值。

参数值制表符补全是最常通过 ValidateSet 参数属性和 PowerShell 动态参数公开的功能。但还有另一种鲜为人知的方法被许多人忽视，那就是论证补全。参数完成器允许您只需几行代码即可在任何 PowerShell 函数上定义制表符完成。

在本文中，您将学习如何使用 Register-ArgumentCompleter cmdlet 创建参数完成器。然后，您将学习如何应用参数完成器并将它们与两个关键示例相结合。

您将使用 Register-ArgumentCompleter 来工作，并通过将参数值作为命令本身的一部分随时可用来节省挖掘有效参数值的时间。

ArgumentCompleters 简单介绍

您可以向任何 PowerShell 命令添加参数完成符以获取 PowerShell 选项卡补全；默认的内置 cmdlet 或自定义函数。我们首先介绍如何为名为 Do-Thing 的自定义函数创建参数。

Do-Thing 函数是一个带有单个参数Name 的简单函数。该函数仅返回通过 Name 参数接收到的值，如下所示。

function Do-Thing {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]$Name
    )
    
    $Name
}

假设您希望支持 Name 参数的值为 foo 和 bar。

创建脚本块来提供值

您可以通过首先创建脚本块来注册参数完成器以提供 foo 和 bar 值。脚本块是当您按下 Tab 键时执行的内容。每次按下 Tab 键时，脚本块都会执行并返回下面数组中的单个字符串元素。

$scriptBlock = { 'foo','bar' }

一旦您获得了作为值提供的项目数组，您就可以注册参数完成器，并提供与参数完成器关联的命令名称和参数名称。请注意，下面您还将提供刚刚创建的脚本块。

PS51> Register-ArgumentCompleter -CommandName Do-Thing -ParameterName Name -ScriptBlock $scriptBlock

现在，当您输入 Do-Thing -Name <tab> 时，PowerShell 将开始滚动浏览脚本块中定义的所有值，在本例中为 foo 和 bar 。

对于每个参数，您只期望一定数量的项目。对于 FoodType，您希望支持 Fruit 和 Vegetable 的值。每个食物类型类别下都有食物名称，如下所示。

带有 ArgumentCompleters 的动态参数值

使用 ValidateSet 参数验证属性可以轻松完成前面的示例，但是如果您需要动态值怎么办？也许您想要提供的值可以随时更改，就像文件夹中的文件一样。

在这种情况下，您只需更改脚本块内的代码即可。由于脚本块内的代码是在运行时执行的，因此它不必是静态列表。它可以动态返回列表。

下面是您可以尝试的另一个示例。

function Get-ProgramFilesFolder {
    [CmdletBinding()]
    param(
        [Parameter()]
        [string]$FolderName
    )
}

$scriptBlock = { Get-ChildItem -Path 'C:\Program Files' | Select-Object -ExpandProperty Name }

Register-ArgumentCompleter -CommandName Get-ProgramFilesFolder -ParameterName FolderName -ScriptBlock $scriptBlock

将参数值传递给脚本块

前面的示例不依赖于脚本块中的任何输入。当用户按下 Tab 键时，它们都只是执行脚本块。更进一步，您还可以将参数完成器传递到脚本块中以更改行为。

当您使用 Register-ArgumentCompleter 将脚本块关联到命令时，PowerShell 将通过位置参数以及关联命令执行时传递的参数传递由 Register-ArgumentCompleter 提供的每个参数值通过位置参数。

要创建脚本块来接受输入，首先必须注意在创建时如何将参数传递给 Register-ArgumentCompleter。一次注册参数完成器的方式以及调用关联命令的方式都很重要。

位置参数和脚本块

这个概念可能会让人困惑，所以让我们用一个例子来分解它。

您首先需要创建一个至少包含两个参数的脚本块，无论关联命令有多少个参数。下面你可以看到我定义了一个带有两个参数的脚本。参数占位符可以是任何名称。为什么它们被称为 $commandName 和 $parameterName？因为它们与传递给 Register-ArgumentCompleter 命令的 CommandName 和 ParameterName 参数的值相关。

当用户按下 Tab 键时，下面的脚本块将仅返回 $commandName 和 $parameterName 的值。

$scriptblock = {
    param($commandName,$parameterName)
    
    $commandName,$parameterName
}

创建脚本块后，使用我们之前的示例命令 Get-ProgramFilesFolder 运行 Register-ArgumentCompleter。

Register-ArgumentCompleter -CommandName Get-ProgramFilesFolder -ParameterName FolderName -ScriptBlock $scriptBlock

键入 Get-ProgramFilesFolder -FolderName <tab>。请注意，制表符补全将循环显示关联命令的名称和参数名称的值。它正在提取 Register-ArgumentCompleter 的 CommandName 和 ParameterName 参数的值。

请记住，如果要将参数传递给脚本块，则必须始终为运行 Register-ArgumentCompleter 时传递的所有参数值添加占位符。

将用户提供的值传递给脚本块

现在您已经了解了 Register-ArgumentCompleter 参数在将值传递给脚本块时所扮演的角色，让我们了解如何将用户提供的值传递给它。

我们再次以 Get-ProgramFilesFolder 函数为例。

您希望允许用户输入一个字符作为 FolderName 参数值，按 Tab 键并仅返回与该字符串匹配的文件夹名称。例如，如果用户键入“a”并开始按 Tab，您只想返回以“a”开头的文件夹。

要构建此行为，您需要向脚本块添加额外的参数值占位符。下面我将占位符命名为 $stringMatch。在用户按下 Tab 键之前，$stringMatch 将保存 FolderName 参数的值。

$scriptblock = {
    param($commandName,$parameterName,$stringMatch)
    
    Get-ChildItem -Path "C:\Program Files$stringMatch*" | Select-Object -ExpandProperty Name
}

Register-ArgumentCompleter -CommandName Get-ProgramFilesFolder -ParameterName FolderName -ScriptBlock $scriptBlock

如果您现在输入 Get-ProgramFilesFolder -FolderName a<tab>，您将看到正在循环浏览所有以“a”开头的文件夹名称。

将 PowerShell 选项卡补全添加到 Get-CimInstance CIM 类

使用参数完成符的一个实际示例是使用 Get-CimInstance cmdlet 上的 ClassName 参数。之前，您学习了如何将参数完成器应用于自定义函数，但内置 cmdlet 也同样可以工作。

当我使用 ClassName 参数和 Get-CimInstance 查询 WMI 时，我永远无法记住所有 CIM 类。当我输入 Get-CimInstance -ClassName <tab> 时，我想循环浏览所有 CIM 类。

收集所有 CIM 课程

第一步是编写代码来查找所有 CIM 类并将它们作为列表中的字符串返回。

Get-CimClass | Where-Object { $_.CimClassName -notlike '__*' } | Sort-Object -Property CimClassName | Select-Object -ExpandProperty CimClassName

创建脚本块

接下来，创建当您尝试使用 Tab 键补全 ClassName 参数值时将执行的脚本块。

$scriptBlock = {
    Get-CimClass | Where-Object { $_.CimClassName -notlike '__*' } | Sort-Object -Property CimClassName | Select-Object -ExpandProperty CimClassName
}

注册 ArgumentCompleter

最后，提供命令名称、参数名称以及当您尝试使用 Tab 键补全 ClassName 参数时要执行的脚本块。

Register-ArgumentCompleter -CommandName Get-CimInstance -ParameterName ClassName -ScriptBlock $scriptBlock

试试看！

现在输入 Get-CimInstance -ClassName <tab>。您会注意到，您现在可以循环浏览所有可用的 CIM 课程！

注意：参数完成符仅在当前会话中有效。这意味着如果您关闭 PowerShell 控制台，它们就会消失！为了解决这个问题，我建议将它们添加到您的 PowerShell 配置文件中，以确保它们在每个会话中注册。

概括

PowerShell 参数完成器可能不是使用最广泛或最著名的，但它们肯定会派上用场。

通过将您自己的制表符补全功能添加到 PowerShell 内的任何命令中，可能会节省您大量的研究时间。

进一步阅读

• Register-ArgumentCompleter Microsoft 文档
• 用其他参数值完成参数值