PowerShell中字符串隐式转为StringBuilder数组问题咨询

问题现象 #

给定输入：

$value='Line"
String'
$value_type='Interpolated'

其中$value包含字面量转义序列（而非实际转义字符），运行_unescape函数后，原本预期的字符串被隐式转换为包含13个System.Text.StringBuilder实例的数组$value2；即使将函数内的循环简化为仅追加字符，仍会出现类似转换，数组长度与返回的字符数完全一致。

转换发生时机 #

这种隐式转换发生在函数返回值被赋值给变量的阶段，本质是PowerShell的自动“展开集合”行为：如果_unescape函数在循环中直接调用StringBuilder.Append()且未处理其返回值，每次Append()都会将自身的StringBuilder实例输出到管道，PowerShell会自动把这些零散输出收集成数组。

典型错误函数写法示例：

function _unescape {
    param($value)
    $sb = [System.Text.StringBuilder]::new()
    foreach ($c in $value.GetEnumerator()) {
        # 错误：直接输出Append的返回值（StringBuilder实例）
        $sb.Append($c)
    }
}

每次$sb.Append($c)都会返回$sb本身，这些返回值会被PowerShell全部收集，最终形成由N个相同StringBuilder实例组成的数组（N为循环执行次数）。

阻止转换的方法 #

1. 捕获Append的返回值，避免输出到管道：在Append调用前添加[void]或赋值给$null，丢弃返回值：

function _unescape {
    param($value)
    $sb = [System.Text.StringBuilder]::new()
    foreach ($c in $value.GetEnumerator()) {
        [void]$sb.Append($c)
        # 等效写法：$null = $sb.Append($c)
    }
    # 仅返回最终构建好的字符串
    return $sb.ToString()
}

2. 明确控制函数输出：确保函数仅在循环结束后输出最终的字符串结果，避免中间过程产生多余输出。

现象解释 #

PowerShell函数默认会将所有未被重定向/捕获的输出（包括命令返回值、表达式结果）收集到输出流，作为函数的返回值。StringBuilder.Append()的设计是返回自身实例（支持链式调用，如$sb.Append('a').Append('b')），如果循环中直接调用该方法且不处理返回值，每一次调用都会把StringBuilder实例推入输出流。当循环执行N次，就会有N个相同实例被收集，最终形成长度等于字符数的数组。

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