Public/Watch-ServerUpgrade.ps1

function Watch-ServerUpgrade {
<#
.SYNOPSIS
    Monitors a remote Windows upgrade across reboot cycles.
.DESCRIPTION
    Waits for SMB, WinRM, and RDP ports to disconnect, then polls management ports
    and CIM until the reported OS build reaches the target or the timeout expires.
    Without ExpectedBuild, returns the first OS details retrieved after recovery;
    recovery alone does not confirm that an upgrade succeeded.
    No Windows release is assumed. Start before the first reboot, or while the
    target is offline. An older build during setup does not end monitoring.
.PARAMETER ComputerName
    The Windows computer to monitor.
.PARAMETER ExpectedBuild
    Optional minimum OS build number that confirms the upgrade. Omit to monitor
    recovery without verifying a target build. Examples: Windows Server 2016 =
    14393, Server 2019 = 17763, Server 2022 = 20348, Server 2025 = 26100;
    Windows 11 22H2 = 22621, 23H2 = 22631, and 24H2 = 26100.
.PARAMETER PollIntervalSeconds
    Delay between checks. Defaults to 15 seconds.
.PARAMETER TimeoutSeconds
    Overall monitoring timeout, including the initial reboot wait. Defaults to 3600.
    In-flight network operations can extend this by their connection timeout.
.PARAMETER Credential
    Optional credentials used to create a CIM session.
.PARAMETER Beep
    Plays an audible success or warning alert when monitoring ends.
.OUTPUTS
    System.Management.Automation.PSCustomObject. ComputerName, ExpectedBuild,
    BuildNumber, OSCaption, Status, ElapsedSeconds, and LastQueryError.
.EXAMPLE
    Watch-ServerUpgrade -ComputerName 'APP01' -ExpectedBuild 26100 -Verbose
    Monitors an upgrade to Windows Server 2025 (or Windows 11 24H2) or newer.
.EXAMPLE
    Watch-ServerUpgrade -ComputerName 'APP01' -ExpectedBuild 20348 -Verbose
    Monitors an upgrade to Windows Server 2022 or newer.
.EXAMPLE
    Watch-ServerUpgrade -ComputerName 'APP01' -Verbose
    Reports OS details after recovery without verifying upgrade success.
#>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$ComputerName,

        [ValidateRange(1, 2147483647)]
        [int]$ExpectedBuild,

        [ValidateRange(1, 2147483647)]
        [int]$PollIntervalSeconds = 15,

        [ValidateRange(1, 2147483647)]
        [int]$TimeoutSeconds = 3600,

        [pscredential]$Credential,
        [switch]$Beep
    )

    if (-not (Get-Command -Name Test-ServerUpgradePort -CommandType Function -ErrorAction SilentlyContinue)) {
        . "$PSScriptRoot\..\Private\Test-ServerUpgradePort.ps1"
    }

    $hasExpectedBuild = $PSBoundParameters.ContainsKey('ExpectedBuild')
    $startTime = Get-Date
    $deadline = $startTime.AddSeconds($TimeoutSeconds)
    $sawOffline = $false
    $recovered = $false
    $os = $null
    $lastQueryError = $null
    $status = 'TimedOut'
    $targetDescription = if ($hasExpectedBuild) { "target build $ExpectedBuild" } else { 'no target build verification' }
    Write-Verbose "[$($startTime.ToString('yyyy-MM-dd HH:mm:ss'))] '$ComputerName': waiting for a reboot; $targetDescription."

    while ((Get-Date) -lt $deadline) {
        $smbOpen = Test-ServerUpgradePort -ComputerName $ComputerName -Port 445
        $winrmOpen = Test-ServerUpgradePort -ComputerName $ComputerName -Port 5985
        $rdpOpen = Test-ServerUpgradePort -ComputerName $ComputerName -Port 3389

        if (-not $smbOpen -and -not $winrmOpen -and -not $rdpOpen) {
            if (-not $sawOffline) {
                Write-Verbose "[$([DateTime]::Now.ToString('yyyy-MM-dd HH:mm:ss'))] '$ComputerName': management ports are offline."
            }
            $sawOffline = $true
        } elseif ($sawOffline) {
            $recovered = $true
            $session = $null
            try {
                $cimParams = @{
                    ClassName = 'Win32_OperatingSystem'
                    OperationTimeoutSec = 10
                    ErrorAction = 'Stop'
                    Verbose = $false
                }
                if ($PSBoundParameters.ContainsKey('Credential')) {
                    $session = New-CimSession -ComputerName $ComputerName -Credential $Credential -OperationTimeoutSec 10 -ErrorAction Stop -Verbose:$false
                    $cimParams.CimSession = $session
                } else {
                    $cimParams.ComputerName = $ComputerName
                }
                $queriedOS = Get-CimInstance @cimParams
                if (-not $queriedOS -or [string]::IsNullOrEmpty([string]$queriedOS.BuildNumber)) {
                    throw 'CIM returned no OS build number.'
                }
                $currentBuild = [int]$queriedOS.BuildNumber
                $os = $queriedOS
                $lastQueryError = $null
                Write-Verbose "[$([DateTime]::Now.ToString('yyyy-MM-dd HH:mm:ss'))] '$ComputerName': $($os.Caption), build $currentBuild."
                if (-not $hasExpectedBuild) {
                    $status = 'Recovered'
                    break
                }
                if ($currentBuild -ge $ExpectedBuild) {
                    $status = 'Succeeded'
                    break
                }
            } catch {
                $lastQueryError = $_.Exception.Message
                Write-Verbose "[$([DateTime]::Now.ToString('yyyy-MM-dd HH:mm:ss'))] '$ComputerName': CIM not ready; retrying. $lastQueryError"
            } finally {
                if ($session) {
                    Remove-CimSession -CimSession $session -ErrorAction SilentlyContinue -Verbose:$false
                }
            }
        }

        $now = Get-Date
        $remaining = ($deadline - $now).TotalSeconds
        if ($remaining -gt 0) {
            $delay = [math]::Min($PollIntervalSeconds, [math]::Ceiling($remaining))
            $elapsed = [math]::Round(($now - $startTime).TotalSeconds, 1)
            $waitingFor = if (-not $sawOffline) {
                'still online; waiting for the first disconnect'
            } elseif (-not $smbOpen -and -not $winrmOpen -and -not $rdpOpen) {
                'still offline; waiting for management ports to recover'
            } elseif ($lastQueryError) {
                'management ports online; waiting for CIM to become available'
            } else {
                "management ports online; waiting for target build $ExpectedBuild"
            }
            Write-Verbose "[$($now.ToString('yyyy-MM-dd HH:mm:ss'))] '$ComputerName': $waitingFor. SMB=$smbOpen; WinRM=$winrmOpen; RDP=$rdpOpen; elapsed ${elapsed}s; next check in ${delay}s."
            Start-Sleep -Seconds $delay
        }
    }

    if ($status -notin @('Succeeded', 'Recovered')) {
        if ($os) {
            $status = 'TargetBuildNotReached'
            Write-Warning "'$ComputerName': target build $ExpectedBuild was not reached before timeout; last reported build $($os.BuildNumber). Setup may still be running or a rollback may have occurred."
        } elseif ($recovered) {
            $status = 'QueryFailed'
            Write-Warning "'$ComputerName': management ports recovered, but the OS build could not be verified before timeout."
        } else {
            Write-Warning "'$ComputerName': timed out waiting for management ports to disconnect and recover."
        }
    }

    if ($Beep) {
        try {
            if ($status -in @('Succeeded', 'Recovered')) {
                [Console]::Beep(1000, 500)
                [Console]::Beep(1200, 500)
                [Console]::Beep(1400, 800)
            } else {
                [Console]::Beep(400, 1000)
            }
        } catch {
            Write-Verbose "'$ComputerName': audible alert unavailable. $($_.Exception.Message)"
        }
    }

    [PSCustomObject]@{
        ComputerName = $ComputerName
        ExpectedBuild = $(if ($hasExpectedBuild) { $ExpectedBuild } else { $null })
        BuildNumber = $(if ($os) { [int]$os.BuildNumber } else { $null })
        OSCaption = $(if ($os) { $os.Caption } else { $null })
        Status = $status
        ElapsedSeconds = [math]::Round(((Get-Date) - $startTime).TotalSeconds, 1)
        LastQueryError = $lastQueryError
    }
}