New-XenTask

Last published : Nov 12, 2026
Creates a new Task object.
Related information
Task cmdlets

Syntax

New-XenTask -HashTable <hashtable> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [<CommonParameters>]
New-XenTask -Record <Task> [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>]
    [-WhatIf] [-Confirm] [<CommonParameters>]
New-XenTask [-PassThru] [-Label <string>] [-Description <string>] [-BestEffort]
    [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

Creates a new Task object.
task.create: Create a new task object which must be manually destroyed.
Task: A long-running asynchronous task.

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

-Confirm

Prompts for confirmation before running the cmdlet.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases cf

-Description

longer description for the new task
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-HashTable

A hashtable of field names to values, from which to create the Task.
Attribute Value
Type hashtable
Required True
Position Named
Accepts pipeline input False

-Label

short label for the new task
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-PassThru

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

-Record

An existing Task record whose fields are used to create the new object.
Attribute Value
Type Task
Required True
Position Named
Accepts pipeline input False

-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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False
Aliases wi

Inputs

  • None

Outputs

  • Task
  • void

Examples

Example 1: Create a Task

PS> New-XenTask -Label "value" -Description "value" -PassThru
New-XenTask takes the arguments of the create call rather than a record of fields, and needs all of them. -PassThru returns the new Task.

Example 2: See what would be created

PS> New-XenTask -Label "value" -Description "value" -WhatIf
Reports what would be created without creating it. Every cmdlet that changes the server takes -WhatIf and -Confirm.

Example 3: Run against a particular session

PS> New-XenTask -Label "value" -Description "value" -PassThru -SessionOpaqueRef $session.opaque_ref
Every cmdlet takes -SessionOpaqueRef, which runs it against a session opened with Connect-XenServer rather than the default one. It is how a script drives more than one server at a time.
  • Task cmdlets
  • Class: Task
  • Using the XenServer PowerShell module