Register-ArgumentCompleter

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

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

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

使用 CommandName 参数调用此命令时，如果没有 ParameterName 或 Native 参数，该命令将像指定 Native 参数一样运行。 这可以防止参数完成程序适用于 PowerShell 命令参数。 如果要为 PowerShell 命令注册参数完成程序，请始终指定 ParameterName 参数。

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

$s = {
    param(
        $commandName,
        $parameterName,
        $wordToComplete,
        $commandAst,
        $fakeBoundParameters
    )

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

第一个命令创建一个脚本块，该块采用所需的参数，当用户按 tab 时传入这些参数。有关详细信息，请参阅 ScriptBlock 参数说明。

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

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

以下示例覆盖 cmdlet 的 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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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 +空格时。 PowerShell 仅使用此功能进行显示。 选择后不会将它传递给命令。
• resultType （CompletionResultType） - 完成结果的类型。
• 工具提示 （字符串） - 工具提示的文本，其中包含有关对象的详细信息。 当用户 在按 Ctrl+空格后选择项目时，这可见。

可以使用 Native 参数为本机命令提供 Tab 补全。 以下示例为 dotnet 命令行接口 （CLI） 添加制表符补全。

$scriptblock = {
    param(
        $wordToComplete,
        $commandAst,
        $cursorPosition
    )

    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

第一个命令创建一个脚本块，该块采用所需的参数，当用户按 tab 时传入这些参数。有关详细信息，请参阅 ScriptBlock 参数说明。

在脚本块中，dotnet complete 命令执行选项卡完成。 结果通过管道传递给 ForEach-Object cmdlet，该 cmdlet 使用 System.Management.Automation.CompletionResult 类的 新 静态方法为每个值创建 CompletionResult 对象。

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

不能用管道将对象传送到此 cmdlet。

此 cmdlet 不返回任何输出。