Wait-XenTask

Last published : Nov 12, 2026
Waits for an asynchronous XenServer task to finish.
Related information
Task cmdlets

Syntax

Wait-XenTask [-Task] <Task> [-PassThru] [-ShowProgress] [-Min <int>] [-Max <int>]
    [-BestEffort] [-SessionOpaqueRef <string>] [<CommonParameters>]
Wait-XenTask [-Ref] <XenRef[Task]> [-PassThru] [-ShowProgress] [-Min <int>] [-Max <int>]
    [-BestEffort] [-SessionOpaqueRef <string>] [<CommonParameters>]
Wait-XenTask [-Uuid] <Guid> [-PassThru] [-ShowProgress] [-Min <int>] [-Max <int>]
    [-BestEffort] [-SessionOpaqueRef <string>] [<CommonParameters>]
Wait-XenTask [-Name] <string> [-PassThru] [-ShowProgress] [-Min <int>] [-Max <int>]
    [-BestEffort] [-SessionOpaqueRef <string>] [<CommonParameters>]

Description

Blocks until the given task completes, then returns its result.
Cmdlets run with -Async return a task straight away instead of waiting. Piping that task into this cmdlet is how to wait for the operation and collect what it produced; -ShowProgress draws a progress bar while it runs.
If the task fails, this cmdlet raises the error the task carries.

Parameters

-BestEffort

If set, the cmdlet continues processing further objects instead of throwing a terminating error when an operation fails for one object.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Max

The percentage the progress bar finishes at, for a task that is one step of a longer operation.
Attribute Value
Type int
Required False
Position Named
Accepts pipeline input False

-Min

The percentage the progress bar starts at, for a task that is one step of a longer operation.
Attribute Value
Type int
Required False
Position Named
Accepts pipeline input False

-Name

The name of the task to wait for.
Attribute Value
Type string
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases name_label

-PassThru

If set, the cmdlet returns the task's result. By default the cmdlet does not generate any output.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Ref

The opaque reference of the task to wait for.
Attribute Value
Type XenRef[Task]
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases opaque_ref

-SessionOpaqueRef

The session object on which to run the cmdlet. This overrides the default session and lets you target a specific open XenServer connection.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-ShowProgress

If set, a progress bar is shown while the task runs.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Task

The task to wait for.
Attribute Value
Type Task
Required True
Position 0
Accepts pipeline input True (ByValue)

-Uuid

The uuid of the task to wait for.
Attribute Value
Type Guid
Required True
Position 0
Accepts pipeline input True (ByPropertyName)

Inputs

  • Task
  • XenRef[Task]
  • Guid
  • string

Examples

Example 1: Wait for an asynchronous operation

PS> Get-XenVM -Name "Demo VM" | Invoke-XenVM -XenAction Start -Async -PassThru | Wait-XenTask -ShowProgress
This is the idiom for any long-running operation: -Async returns a task, and Wait-XenTask follows it to completion.

Example 2: Collect what the task produced

PS> $task = Get-XenVM -Name "Demo VM" | Invoke-XenVM -XenAction Snapshot -Async -PassThru
PS> $snapshot = $task | Wait-XenTask -PassThru
An operation that creates something returns it through the task, so -PassThru is what hands back the new object.

Example 3: Wait for a task by reference

PS> Wait-XenTask -Ref OpaqueRef:f433bf7b-2b0c-5f53-7018-7d195addb3ca -ShowProgress
A task can be waited for by reference, uuid or name as well as by piping the object in.
  • Task cmdlets
  • Class: Task
  • Using the XenServer PowerShell module