如何确保steppable pipeline使用的文件在异常时仍能关闭？

这是一个自问自答的问题。我将仅提供适用于PowerShell 7.3及更高版本的答案，欢迎补充适用于旧版本的答案。

我有一个接收管道输入的自定义日志函数，它使用可分步管道(steppable pipeline)对象将输入正确转发到Out-File。当包含该日志函数的管道中任意命令抛出异常（又称脚本终止错误）且异常被捕获时，Out-File打开的文件不会关闭，后续尝试向该文件添加内容（如使用Add-Content）会失败，错误信息如下：

无法访问文件“C:\LogFile.log”，因为它正被另一进程使用。

可复现示例 #

$LOG_FILE_PATH = Join-Path $PSScriptRoot LogFile.log

Function Test-SteppablePipeline {

    [CmdletBinding()]
    param (
        [Parameter( Mandatory, ValueFromPipeline )]
        [string] $InputObject
    )

    begin {
        Write-Host '[begin]'

        $steppablePipeline = {
            Out-File -LiteralPath $LOG_FILE_PATH
        }.GetSteppablePipeline( $MyInvocation.CommandOrigin )

        $steppablePipeline.Begin( $true )
    }

    process {
        Write-Host '[process]'
        
        $steppablePipeline.Process( $InputObject )

        $InputObject  # 转发到调用方管道中的下一个命令
    }

    end {
        Write-Host '[end]'

        $steppablePipeline.End()
    }
}

try {
    'foo', 'bar' | 
        ForEach-Object { throw 'my error' } |
        Test-SteppablePipeline
}
catch {
    '[catch]'
}

Write-Host '[add]'
Add-Content -LiteralPath $LOG_FILE_PATH -Value 'baz'

输出结果 #

[begin]
[process]
[catch]
[add]
Add-Content: C:\Test.ps1:48
Line |
  48 |  Add-Content -LiteralPath $LOG_FILE_PATH -Value 'baz'
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | The process cannot access the file 'C:\LogFile.log' because it is being used by another process.

从输出的消息可以看到，由于异常，Test-SteppablePipeline的end块未被调用，这正是文件未关闭的原因。

在PowerShell 7.3及以上版本中，可利用PSCmdlet.RegisterCleanupAction方法注册清理逻辑，确保无论管道是否因异常终止，分步管道的收尾方法都会执行，从而正确关闭文件句柄。

修改后的函数如下：

$LOG_FILE_PATH = Join-Path $PSScriptRoot LogFile.log

Function Test-SteppablePipeline {

    [CmdletBinding()]
    param (
        [Parameter( Mandatory, ValueFromPipeline )]
        [string] $InputObject
    )

    begin {
        Write-Host '[begin]'

        $steppablePipeline = {
            Out-File -LiteralPath $LOG_FILE_PATH
        }.GetSteppablePipeline( $MyInvocation.CommandOrigin )
        
        $steppablePipeline.Begin( $true )

        # 注册清理动作，确保管道结束（正常/异常）时执行收尾
        $null = $PSCmdlet.RegisterCleanupAction({
            $steppablePipeline.End()
            $steppablePipeline.Dispose()
        })
    }

    process {
        Write-Host '[process]'
        
        $steppablePipeline.Process( $InputObject )

        $InputObject  # 转发到调用方管道中的下一个命令
    }

    end {
        Write-Host '[end]'
    }
}

try {
    'foo', 'bar' | 
        ForEach-Object { throw 'my error' } |
        Test-SteppablePipeline
}
catch {
    '[catch]'
}

Write-Host '[add]'
Add-Content -LiteralPath $LOG_FILE_PATH -Value 'baz'

原理说明 #

• RegisterCleanupAction是PowerShell 7.3新增的方法，它会在命令生命周期结束时自动执行注册的脚本块，不受管道异常终止的影响。
• 通过调用steppablePipeline.End()，确保Out-File完成文件写入并关闭句柄；调用Dispose()则彻底释放分步管道占用的资源，避免资源泄漏。

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