PowerShell：如何为代理函数实现自动补全功能？

问题场景 #

我编写了一个简单的包装函数，用来快速调用带-Full参数的Get-Help：

function helf {
    Get-Help -Full @args
}

但执行helf -<tab>时，参数自动补全功能完全失效，测试结果如下：

> TabExpansion2 "helf -" | select -Expand CompletionMatches
[ NO RESULT ]

对比示例：oss函数的正常补全 #

注意到系统自带的oss函数并非Out-String的别名，而是Out-String -Stream的代理函数，它却能正常触发参数自动补全：

首先查看oss的命令类型：

> gcm oss

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        oss

测试Out-String -Stream -的补全结果：

> TabExpansion2 "Out-String -Stream -" | select -Expand CompletionMatches

CompletionText       ListItemText           ResultType ToolTip
--------------       ------------           ---------- -------
-Width               Width               ParameterName [int] Width
-InputObject         InputObject         ParameterName [psobject] InputObject
-Verbose             Verbose             ParameterName [switch] Verbose
-Debug               Debug               ParameterName [switch] Debug
-ErrorAction         ErrorAction         ParameterName [ActionPreference] ErrorAction
-WarningAction       WarningAction       ParameterName [ActionPreference] WarningAction
-InformationAction   InformationAction   ParameterName [ActionPreference] InformationAction
-ProgressAction      ProgressAction      ParameterName [ActionPreference] ProgressAction
-ErrorVariable       ErrorVariable       ParameterName [string] ErrorVariable
-WarningVariable     WarningVariable     ParameterName [string] WarningVariable
-InformationVariable InformationVariable ParameterName [string] InformationVariable
-OutVariable         OutVariable         ParameterName [string] OutVariable
-OutBuffer           OutBuffer           ParameterName [int] OutBuffer
-PipelineVariable    PipelineVariable    ParameterName [string] PipelineVariable

测试oss -的补全结果，和上面完全一致：

> TabExpansion2 "oss -" | select -Expand CompletionMatches

CompletionText       ListItemText           ResultType ToolTip
--------------       ------------           ---------- -------
-Width               Width               ParameterName [int] Width
-InputObject         InputObject         ParameterName [psobject] InputObject
-Verbose             Verbose             ParameterName [switch] Verbose
-Debug               Debug               ParameterName [switch] Debug
-ErrorAction         ErrorAction         ParameterName [ActionPreference] ErrorAction
-WarningAction       WarningAction       ParameterName [ActionPreference] WarningAction
-InformationAction   InformationAction   ParameterName [ActionPreference] InformationAction
-ProgressAction      ProgressAction      ParameterName [ActionPreference] ProgressAction
-ErrorVariable       ErrorVariable       ParameterName [string] ErrorVariable
-WarningVariable     WarningVariable     ParameterName [string] WarningVariable
-InformationVariable InformationVariable ParameterName [string] InformationVariable
-OutVariable         OutVariable         ParameterName [string] OutVariable
-OutBuffer           OutBuffer           ParameterName [int] OutBuffer
-PipelineVariable    PipelineVariable    ParameterName [string] PipelineVariable

解决方案 #

方式一：注册参数补全器 #

直接为helf函数绑定Get-Help的参数补全逻辑，不需要修改函数本身的结构：

# 保留原函数
function helf {
    Get-Help -Full @args
}

# 注册参数补全，让helf继承Get-Help的参数补全逻辑
Register-ArgumentCompleter -CommandName helf -ScriptBlock {
    param($wordToComplete, $commandAst, $cursorPosition)
    # 调用Get-Help的补全逻辑并返回结果
    $completionResult = TabExpansion2 "Get-Help $wordToComplete" $commandAst $cursorPosition
    $completionResult.CompletionMatches
}

执行以上代码后，再次尝试helf -<tab>就能正常触发Get-Help的参数补全。

方式二：生成规范的代理函数 #

通过PowerShell的ProxyCommand类生成包含完整参数元数据的代理函数，这样自动补全会原生支持，同时还能保留目标命令的所有参数特性：

# 获取Get-Help的命令元数据
$originalCmd = Get-Command Get-Help
# 生成基础代理代码
$proxyCode = [System.Management.Automation.ProxyCommand]::Create($originalCmd)
# 修改代理代码，默认添加-Full参数
$proxyCode = $proxyCode -replace 'begin {', 'begin { $PSBoundParameters["Full"] = $true;'
# 创建helf函数
Invoke-Expression "function helf { $proxyCode }"

这种方式生成的helf函数和系统自带的oss逻辑一致，拥有Get-Help的全部参数元数据，自动补全、参数验证等特性都会原生生效。

原理说明 #

PowerShell的参数自动补全依赖于命令的参数元数据（如[Parameter()]属性、参数类型定义等）。简单的包装函数因为没有显式定义参数信息，PowerShell无法识别需要补全的参数列表；而oss这类系统代理函数是通过规范流程生成的，包含了目标命令的完整参数元数据，因此自动补全可以正常触发。

内容的提问来源于stack exchange，提问作者Dmitrij Drandarov