Private/Invoke-Process.ps1

function Invoke-Process {
    <#PSScriptInfo
    .VERSION 1.4
    .GUID b787dc5d-8d11-45e9-aeef-5cf3a1f690de
    .AUTHOR Adam Bertram
    .COMPANYNAME Adam the Automator, LLC
    .TAGS Processes
    #>

    <#
    .SYNOPSIS
        Starts a process, captures its output, and validates its exit code.

    .DESCRIPTION
        Standard output is returned as a single string. Standard error is written
        to the error stream on success and included in the terminating error on
        failure. The process is stopped if it exceeds the timeout or output limit.

    .PARAMETER FilePath
        Executable path or command name to start.

    .PARAMETER ArgumentList
        Individual process arguments. Each argument is escaped for the Windows
        command-line convention used by Start-Process.

    .PARAMETER SuccessExitCodes
        Exit codes that indicate success. Defaults to 0.

    .PARAMETER TimeoutSeconds
        Maximum process duration in seconds. Defaults to 1800.

    .PARAMETER MaximumOutputBytes
        Maximum combined size of captured standard output and standard error.
        Defaults to 10 MiB.
    #>

    [CmdletBinding(SupportsShouldProcess = $true)]
    param (
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [System.String] $FilePath,

        [Parameter()]
        [AllowEmptyCollection()]
        [System.Object[]] $ArgumentList,

        # Exit codes treated as success. Some tools (e.g. robocopy) use non-zero codes for success
        [Parameter()]
        [System.Int32[]] $SuccessExitCodes = @(0),

        [Parameter()]
        [ValidateRange(1, 2147483)]
        [System.Int32] $TimeoutSeconds = 1800,

        [Parameter()]
        [ValidateRange(1, 2147483647)]
        [System.Int64] $MaximumOutputBytes = 10MB
    )

    $ErrorActionPreference = "Stop"
    $stdOutTempFile = $null
    $stdErrTempFile = $null
    $cmd = $null
    try {
        if ($PSCmdlet.ShouldProcess("Process [$($FilePath)]", "Run")) {
            $stdOutTempFile = [System.IO.Path]::GetTempFileName()
            $stdErrTempFile = [System.IO.Path]::GetTempFileName()

            $quoteArgument = {
                param ([System.String] $Value)

                $Builder = New-Object System.Text.StringBuilder
                [void]$Builder.Append([char]34)
                $BackslashCount = 0
                for ($Index = 0; $Index -lt $Value.Length; $Index++) {
                    $Character = $Value[$Index]
                    if ($Character -eq [char]92) {
                        $BackslashCount++
                        continue
                    }

                    if ($Character -eq [char]34) {
                        for ($Slash = 0; $Slash -lt (2 * $BackslashCount + 1); $Slash++) {
                            [void]$Builder.Append([char]92)
                        }
                        [void]$Builder.Append([char]34)
                    }
                    else {
                        for ($Slash = 0; $Slash -lt $BackslashCount; $Slash++) {
                            [void]$Builder.Append([char]92)
                        }
                        [void]$Builder.Append($Character)
                    }
                    $BackslashCount = 0
                }

                for ($Slash = 0; $Slash -lt (2 * $BackslashCount); $Slash++) {
                    [void]$Builder.Append([char]92)
                }
                [void]$Builder.Append([char]34)
                $Builder.ToString()
            }
            $quotedArguments = foreach ($Argument in $ArgumentList) {
                & $quoteArgument $Argument
            }

            $startProcessParams = @{
                FilePath               = $FilePath
                RedirectStandardError  = $stdErrTempFile
                RedirectStandardOutput = $stdOutTempFile
                PassThru               = $true
                NoNewWindow            = $true
            }
            if ($PSBoundParameters.ContainsKey("ArgumentList") -and
                ($null -eq $ArgumentList -or $ArgumentList.Count -gt 0)) {
                $startProcessParams.ArgumentList = $quotedArguments -join " "
            }
            $cmd = Start-Process @startProcessParams
            # Retain the handle so Windows PowerShell 5.1 can read the exit code after the process exits.
            [void]$cmd.Handle

            $stopReason = $null
            $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
            do {
                $exited = $cmd.WaitForExit(100)
                $capturedBytes = (Get-Item -LiteralPath $stdOutTempFile -ErrorAction "Stop").Length +
                    (Get-Item -LiteralPath $stdErrTempFile -ErrorAction "Stop").Length

                if ($capturedBytes -gt $MaximumOutputBytes) {
                    $stopReason = "Process '$FilePath' exceeded the output limit of $MaximumOutputBytes bytes."
                    break
                }
                if (-not $exited -and $stopwatch.Elapsed.TotalSeconds -ge $TimeoutSeconds) {
                    $stopReason = "Process '$FilePath' exceeded the timeout of $TimeoutSeconds seconds."
                    break
                }
            } until ($exited)

            if ($stopReason) {
                try {
                    if (-not $cmd.HasExited) { $cmd.Kill() }
                    $cmd.WaitForExit()
                }
                catch [System.InvalidOperationException] {
                    if (-not $cmd.HasExited) { throw }
                }
                throw $stopReason
            }

            $cmd.WaitForExit()
            $cmdOutput = Get-Content -LiteralPath $stdOutTempFile -Raw -ErrorAction "Stop"
            $cmdError = Get-Content -LiteralPath $stdErrTempFile -Raw -ErrorAction "Stop"
            if ($SuccessExitCodes -notcontains $cmd.ExitCode) {
                $detail = if ($cmdError) { $cmdError.Trim() } elseif ($cmdOutput) { $cmdOutput.Trim() } else { "No output captured." }
                throw "Process '$FilePath' exited with code $($cmd.ExitCode). $detail"
            }
            if ([System.String]::IsNullOrEmpty($cmdOutput) -eq $false) {
                Write-Output -InputObject $cmdOutput
            }
            if (-not [System.String]::IsNullOrWhiteSpace($cmdError)) {
                Write-Error -Message $cmdError.Trim() -ErrorAction "Continue"
            }
        }
    }
    catch {
        $PSCmdlet.ThrowTerminatingError($_)
    }
    finally {
        if ($cmd -and -not $cmd.HasExited) {
            try {
                $cmd.Kill()
                $cmd.WaitForExit()
            }
            catch {
                Write-Warning -Message "Unable to stop process '$FilePath' during cleanup: $($_.Exception.Message)"
            }
        }
        if ($cmd) { $cmd.Dispose() }

        foreach ($TempFile in $stdOutTempFile, $stdErrTempFile) {
            if ($TempFile -and (Test-Path -LiteralPath $TempFile -PathType "Leaf")) {
                try {
                    Remove-Item -LiteralPath $TempFile -Force -ErrorAction "Stop"
                }
                catch {
                    Write-Warning -Message "Unable to remove temporary process output file '$TempFile': $($_.Exception.Message)"
                }
            }
        }
    }
}