Public/Wait-PrismTask.ps1

function Wait-PrismTask {
    <#
    .SYNOPSIS
        Waits for a Prism Central task to finish.
 
    .DESCRIPTION
        Polls Get-PrismTask until the task status is SUCCEEDED, FAILED or CANCELED.
        Returns the final task object provided by Get-PrismTask,
        including when the task fails or is canceled. Request errors stop polling.
 
    .PARAMETER PrismSession
        The server/FQDN of the PrismSession to use. May be omitted when only one session exists.
 
    .PARAMETER ExtId
        The external identifier of the task to wait for. Pass the .extId
        value returned by an asynchronous operation directly.
 
    .PARAMETER Task
        A PrismTask to wait for, either explicitly or from the pipeline. Uses its
        ExtId and originating PrismSession unless -PrismSession is specified.
 
    .PARAMETER PollIntervalSeconds
        Seconds between status requests. Defaults to 5. The first request is immediate.
 
    .PARAMETER TimeoutSeconds
        Time budget per task, including status requests, session validation, retry
        waits and poll intervals. When omitted, polling has no overall time limit;
        each status request still has its normal request budget. A retry that cannot
        fit its required wait fails early. Whole-second HTTP timeout rounding and
        transport/DNS or scheduling overhead can cause a small overrun. A terminal
        status received after the deadline is still returned; a non-terminal one
        throws the timeout without sleeping again.
 
    .PARAMETER DisplayUpdates
        Writes timestamped task status changes to the information stream using
        Write-Host. Repeated statuses are suppressed for each task being waited on.
 
    .EXAMPLE
        $task = Start-PrismVM -ExtId $vmId
        Wait-PrismTask -Task $task -DisplayUpdates
 
    .EXAMPLE
        Wait-PrismTask -ExtId $taskId -PrismSession 'pc.lab.local' -PollIntervalSeconds 10
 
    .OUTPUTS
        The final PrismTask, including failed or canceled tasks.
    #>


    [CmdletBinding(DefaultParameterSetName = 'ByTask')]
    [OutputType([PrismTask])]
    param(
        [Parameter(Mandatory = $false,
            HelpMessage = 'Prism Session Name')][string]$PrismSession,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'ById',
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true,
            HelpMessage = 'Task external identifier')]
        [Alias('Id', 'TaskExtId')][ValidateNotNullOrEmpty()][string]$ExtId,

        [Parameter(Mandatory = $true, ParameterSetName = 'ByTask', ValueFromPipeline = $true)]
        [ValidateNotNull()][PrismTask]$Task,

        [Parameter(Mandatory = $false)]
        [ValidateRange(1, 2147483647)][int]$PollIntervalSeconds = 5,

        [Parameter(Mandatory = $false)]
        [ValidateRange(1, 2147483647)][int]$TimeoutSeconds,

        [Parameter(Mandatory = $false)][switch]$DisplayUpdates
    )

    process {
        $taskId = if ($PSCmdlet.ParameterSetName -eq 'ByTask') { $Task.ExtId } else { $ExtId }
        if ([string]::IsNullOrWhiteSpace($taskId)) { throw 'A task ExtId is required.' }
        $sessionName = if ($PSCmdlet.ParameterSetName -eq 'ByTask' -and -not $PSBoundParameters.ContainsKey('PrismSession')) {
            $Task.PrismSession
        } else { $PrismSession }
        $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
        $deadlineSplat = @{}
        if ($TimeoutSeconds -gt 0) {
            $deadlineSplat.Deadline = [DateTimeOffset]::UtcNow.AddSeconds($TimeoutSeconds)
        }
        $lastDisplayedStatus = $null
        while ($true) {
            if ($TimeoutSeconds -gt 0 -and $stopwatch.Elapsed.TotalSeconds -ge $TimeoutSeconds) {
                throw [System.TimeoutException]::new("Task '$taskId' did not finish within $TimeoutSeconds seconds.")
            }

            try {
                $currentTask = Get-PrismTask -PrismSession $sessionName -ExtId $taskId @deadlineSplat -ErrorAction Stop
            } catch [TimeoutException] {
                if ($TimeoutSeconds -le 0) { throw }
                throw [TimeoutException]::new("Task '$taskId' could not finish within its $TimeoutSeconds-second budget. $($_.Exception.Message)", $_.Exception)
            }
            if ([string]::IsNullOrWhiteSpace($currentTask.Status)) {
                throw "Task '$taskId' response did not contain a task status."
            }

            if ($DisplayUpdates.IsPresent -and $currentTask.Status -cne $lastDisplayedStatus) {
                Write-Host "[$([datetimeoffset]::Now.ToString('o'))] Task '$taskId': $($currentTask.Status)"
                $lastDisplayedStatus = $currentTask.Status
            }

            if ($currentTask.Status -in @('SUCCEEDED', 'FAILED', 'CANCELED')) {
                return $currentTask
            }

            if ($TimeoutSeconds -gt 0) {
                $remainingMilliseconds = ($TimeoutSeconds * 1000.0) - $stopwatch.Elapsed.TotalMilliseconds
                if ($remainingMilliseconds -le 0) {
                    throw [System.TimeoutException]::new("Task '$taskId' did not finish within $TimeoutSeconds seconds.")
                }
                # Cap the conversion at Int32.MaxValue milliseconds (about 24.9 days),
                # not an infinite wait. Normally the poll interval or timeout is much shorter.
                $sleepMilliseconds = [Math]::Min([double][int]::MaxValue, [Math]::Min($PollIntervalSeconds * 1000.0, $remainingMilliseconds))
                Start-Sleep -Milliseconds ([int][Math]::Ceiling($sleepMilliseconds))
            } else {
                # Sleep in milliseconds so a large PollIntervalSeconds cannot overflow
                # Start-Sleep -Seconds (which caps near Int32.MaxValue / 1000 seconds).
                $sleepMilliseconds = [Math]::Min([double][int]::MaxValue, $PollIntervalSeconds * 1000.0)
                Start-Sleep -Milliseconds ([int][Math]::Ceiling($sleepMilliseconds))
            }
        }
    }
}