为已有PowerShell函数添加可选[ref]参数后调用报错求助

我有一个长期使用的PowerShell函数，新增了一个可选的[ref]类型参数failedJobs，函数头定义如下：

function Wait-ForRunningJobs
{
    Param(
        $jobs,
        [int]$jobsLimit,
        [Switch]$SilentlyContinue,
        [switch]$writeOutput,
        [switch]$noTabs,
        [switch]$failOnError,
        [switch]$keepFailedJobs,
        [Parameter(Mandatory = $false)]
        [ref]$failedJobs
    )
    # 函数逻辑...
}

当显式通过参数名传递[ref]类型值时，调用正常：

Wait-ForRunningJobs -failedJobs ([ref]$failedJobsList) -jobs $jobs -writeOutput -noTabs -keepFailedJobs -SilentlyContinue

但使用以下两种调用方式时会报错：

1. 位置参数调用：

Wait-ForRunningJobs $jobs $asyncJobsLimit -writeOutput -SilentlyContinue $shouldIgnoreErrors

2. 命名参数但给Switch参数传布尔值：

Wait-ForRunningJobs -jobs $jobs -jobsLimit $asyncJobsLimit -writeOutput $true -SilentlyContinue $true -failOnError $shouldIgnoreErrors

报错信息：

Cannot process argument transformation on parameter 'failedJobs'. Reference type is expected in argument.

1. 修正Switch参数的调用方式 #

PowerShell的[switch]类型参数不需要手动传递布尔值，直接使用参数名即可开启开关；如果需要显式控制开关状态，要使用-参数名:$布尔值的格式，不能单独传值。

错误调用：

-writeOutput $true -SilentlyContinue $true -failOnError $shouldIgnoreErrors

正确调用：

# 开启指定开关
-writeOutput -SilentlyContinue -failOnError:$shouldIgnoreErrors
# 显式关闭开关（如需）
-writeOutput:$false

2. 避免位置参数误绑定到failedJobs #

由于failedJobs是[ref]类型参数且未指定Position属性，PowerShell会按参数定义顺序自动分配位置序号。当调用时传递多余的位置值，会被误绑定到failedJobs，导致类型不匹配。

给failedJobs参数添加Position属性，设置为最大值强制只能通过命名参数调用：

[Parameter(Mandatory = $false, Position = [int]::MaxValue)]
[ref]$failedJobs

这样所有位置参数会优先绑定到前面的参数，不会意外匹配到failedJobs。

3. 修正后的完整调用示例 #

针对之前的错误调用，修正后的版本：

# 位置参数调用修正版
Wait-ForRunningJobs $jobs $asyncJobsLimit -writeOutput -SilentlyContinue -failOnError:$shouldIgnoreErrors

# 命名参数调用修正版
Wait-ForRunningJobs -jobs $jobs -jobsLimit $asyncJobsLimit -writeOutput -SilentlyContinue -failOnError:$shouldIgnoreErrors

内容的提问来源于stack exchange，提问作者Yirmi Oppenhime