使用ForEach-Object -Parallel时[ref]引用全局变量报错排查

问题场景 #

编写了一个使用ForEach-Object -Parallel循环的函数，尝试向对话框报告任务进度，核心代码如下：

参数块 #

[Parameter(Mandatory = $false)]
[System.Management.Automation.ScriptBlock]
$ProgressReporter

循环部分 #

# 定义任务总数
$totalTasks = $List.Count
$global:taskIndex = 0

$List | ForEach-Object -Parallel {

    $totalTasks          =  $Using:totalTasks
    $ProgressReporter    =  $Using:ProgressReporter

    # 在并行块内计算并报告进度
    $currentTaskIndex = [System.Threading.Interlocked]::Increment([ref]$global:taskIndex)
    [int] $progress = [math]::Round(($currentTaskIndex / $totalTasks) * 100)

    $ProgressReporter.Invoke($progress)
    # ... 其他任务代码
}

运行时出现错误：

Line |
17 | $currentTaskIndex = [System.Threading.Interlocked]::Incre …
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
| [ref] cannot be applied to a variable that does not exist.

已在循环前显式定义$global:taskIndex = 0，但仍触发该错误。

错误原因 #

ForEach-Object -Parallel会启动多个独立的PowerShell子会话执行并行代码，子会话不会自动继承父会话的全局变量。当你在并行块中直接使用[ref]$global:taskIndex时，子会话中尚未加载该全局变量，因此报错“变量不存在”。

解决方案 #

方案1：显式触发全局变量加载 #

在并行块中先访问一次$global:taskIndex，强制子会话从父会话复制该变量到自身全局作用域，之后再使用[ref]：

$List | ForEach-Object -Parallel {
    $totalTasks = $Using:totalTasks
    $ProgressReporter = $Using:ProgressReporter

    # 先显式访问全局变量，确保子会话中存在该变量
    $null = $global:taskIndex
    $currentTaskIndex = [System.Threading.Interlocked]::Increment([ref]$global:taskIndex)
    [int]$progress = [math]::Round(($currentTaskIndex / $totalTasks) * 100)

    $ProgressReporter.Invoke($progress)
    # ... 其他任务代码
}

方案2：使用引用类型计数器（推荐） #

避免使用全局变量，改用引用类型对象（如自定义对象）存储计数器，通过$Using传递到子会话，这样线程安全的递增操作可以直接作用于对象的属性：

# 循环前定义引用类型计数器
$counter = [pscustomobject]@{ Value = 0 }
$totalTasks = $List.Count

$List | ForEach-Object -Parallel {
    $totalTasks = $Using:totalTasks
    $ProgressReporter = $Using:ProgressReporter
    $counter = $Using:counter

    # 递增计数器的Value属性
    $currentTaskIndex = [System.Threading.Interlocked]::Increment([ref]$counter.Value)
    [int]$progress = [math]::Round(($currentTaskIndex / $totalTasks) * 100)

    $ProgressReporter.Invoke($progress)
    # ... 其他任务代码
}

说明 #

方案2更推荐，因为全局变量可能引发跨会话、跨脚本的冲突，而引用类型计数器仅作用于当前上下文，安全性更高。

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