Invoke-XenVDI

Last published : Nov 12, 2026
Invokes an operation on a VDI object.
Related information
VDI cmdlets

Syntax

Invoke-XenVDI [-VDI] <VDI>
    -XenAction {Snapshot | Clone | Resize | ResizeOnline | Introduce | Update | Copy | Forget | OpenDatabase | ReadDatabasePoolUuid | PoolMigrate | EnableCbt | DisableCbt | DataDestroy | ListChangedBlocks | Revert}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVDI [-Ref] <XenRef[VDI]>
    -XenAction {Snapshot | Clone | Resize | ResizeOnline | Introduce | Update | Copy | Forget | OpenDatabase | ReadDatabasePoolUuid | PoolMigrate | EnableCbt | DisableCbt | DataDestroy | ListChangedBlocks | Revert}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVDI [-Uuid] <guid>
    -XenAction {Snapshot | Clone | Resize | ResizeOnline | Introduce | Update | Copy | Forget | OpenDatabase | ReadDatabasePoolUuid | PoolMigrate | EnableCbt | DisableCbt | DataDestroy | ListChangedBlocks | Revert}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]
Invoke-XenVDI [-Name] <string>
    -XenAction {Snapshot | Clone | Resize | ResizeOnline | Introduce | Update | Copy | Forget | OpenDatabase | ReadDatabasePoolUuid | PoolMigrate | EnableCbt | DisableCbt | DataDestroy | ListChangedBlocks | Revert}
    [-PassThru] [-BestEffort] [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [-Async]
    [<CommonParameters>]

Description

Invokes an operation on a VDI object. Use the -XenAction parameter to select which operation to perform.
Snapshot: Take a read-only snapshot of the VDI, returning a reference to the snapshot. If any driver\_params are specified then these are passed through to the storage-specific substrate driver that takes the snapshot. NB the snapshot lives in the same Storage Repository as its parent.
Clone: Take an exact copy of the VDI and return a reference to the new disk. If any driver\_params are specified then these are passed through to the storage-specific substrate driver that implements the clone operation. NB the clone lives in the same Storage Repository as its parent.
Resize: Resize the VDI.
ResizeOnline: Resize the VDI which may or may not be attached to running guests.
Introduce: Create a new VDI record in the database only.
Update: Ask the storage backend to refresh the fields in the VDI object.
Copy: Copy either a full VDI or the block differences between two VDIs into either a fresh VDI or an existing VDI.
Forget: Removes a VDI record from the database.
OpenDatabase: Load the metadata found on the supplied VDI and return a session reference which can be used in API calls to query its contents.
ReadDatabasePoolUuid: Check the VDI cache for the pool UUID of the database on this VDI.
PoolMigrate: Migrate a VDI, which may be attached to a running guest, to a different SR. The destination SR must be visible to the guest.
EnableCbt: Enable changed block tracking for the VDI. This call is idempotent - enabling CBT for a VDI for which CBT is already enabled results in a no-op, and no error will be thrown.
DisableCbt: Disable changed block tracking for the VDI. This call is only allowed on VDIs that support enabling CBT. It is an idempotent operation - disabling CBT for a VDI for which CBT is not enabled results in a no-op, and no error will be thrown.
DataDestroy: Delete the data of the snapshot VDI, but keep its changed block tracking metadata. When successful, this call changes the type of the VDI to cbt\_metadata. This operation is idempotent: calling it on a VDI of type cbt\_metadata results in a no-op, and no error will be thrown.
ListChangedBlocks: Compare two VDIs in 64k block increments and report which blocks differ. This operation is not allowed when vdi\_to is attached to a VM.
Revert: Copy the contents of a snapshot to the VDI it's related to. The original contents of the VDI are lost.

Parameters

-Async

If set, the operation runs asynchronously and returns a Task object that can be used to track its progress.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-BaseVdi

The base VDI (only required if copying only changed blocks, by default all blocks will be copied). Accepted when -XenAction is Copy.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-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

-DriverParams

Optional parameters that can be passed through to backend driver in order to specify storage-type-specific snapshot options. Accepted when -XenAction is Snapshot, Clone.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-IntoVdi

The destination VDI to copy blocks into (if omitted then a destination SR must be provided and a fresh VDI will be created). Accepted when -XenAction is Copy.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-IsASnapshot

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Location

location information. Accepted when -XenAction is Introduce.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Managed

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-MetadataOfPool

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type XenRef[Pool]
Required False
Position Named
Accepts pipeline input False

-Name

The name of the VDI to operate on.
Attribute Value
Type string
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases name_label

-NameDescription

The description of the disk record. Accepted when -XenAction is Introduce.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-NameLabel

The name of the disk record. Accepted when -XenAction is Introduce.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-Options

Extra parameters. Supports: "dest-img-format" (raw|vhd|qcow2) to specify the image format to use on the destination SR. Accepted when -XenAction is PoolMigrate.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-OtherConfig

additional configuration. Accepted when -XenAction is Introduce.
Attribute Value
Type hashtable
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

-PhysicalUtilisation

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-ReadOnly

true if this disk may ONLY be mounted read-only. Accepted when -XenAction is Introduce.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Ref

The VDI object to operate on, specified by its opaque reference.
Attribute Value
Type XenRef[VDI]
Required True
Position 0
Accepts pipeline input True (ByPropertyName)
Aliases opaque_ref

-SR

The SR that the VDI is in. Accepted when -XenAction is Introduce, Copy, PoolMigrate.
Attribute Value
Type XenRef[SR]
Required False
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

-Sharable

true if this disk may be shared. Accepted when -XenAction is Introduce.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Size

The new size of the VDI. Accepted when -XenAction is Resize, ResizeOnline.
Attribute Value
Type long
Required False
Position Named
Accepts pipeline input False

-SmConfig

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

-Snapshot

The snapshot to which we want to revert. Accepted when -XenAction is Revert.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-SnapshotOf

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-SnapshotTime

Storage-specific config. When the timezone is missing, UTC is assumed. Accepted when -XenAction is Introduce.
Attribute Value
Type DateTime
Required False
Position Named
Accepts pipeline input False

-Type

The type of the VDI. Accepted when -XenAction is Introduce.
Attribute Value
Type vdi_type
Required False
Position Named
Accepts pipeline input False
Accepted values system, user, ephemeral, suspend, crashdump, ha_statefile, metadata, redo_log, rrd, pvs_cache, cbt_metadata, unknown

-Uuid

The UUID of the VDI to operate on.
Attribute Value
Type guid
Required True
Position 0
Accepts pipeline input True (ByPropertyName)

-UuidParam

The uuid of the disk to introduce. Accepted when -XenAction is Introduce.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-VDI

The VDI object to operate on.
Attribute Value
Type VDI
Required True
Position 0
Accepts pipeline input True (ByValue)

-VdiFrom

The first VDI. Accepted when -XenAction is ListChangedBlocks.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-VdiTo

The second VDI. Accepted when -XenAction is ListChangedBlocks.
Attribute Value
Type XenRef[VDI]
Required False
Position Named
Accepts pipeline input False

-VirtualSize

Storage-specific config. Accepted when -XenAction is Introduce.
Attribute Value
Type long
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

-XenAction

Selects which action to use.
Attribute Value
Type XenVDIAction
Required True
Position Named
Accepts pipeline input False
Accepted values Snapshot, Clone, Resize, ResizeOnline, Introduce, Update, Copy, Forget, OpenDatabase, ReadDatabasePoolUuid, PoolMigrate, EnableCbt, DisableCbt, DataDestroy, ListChangedBlocks, Revert

-XenstoreData

Data to insert into xenstore. Accepted when -XenAction is Introduce.
Attribute Value
Type hashtable
Required False
Position Named
Accepts pipeline input False

Inputs

  • VDI
  • XenRef[VDI]
  • guid
  • string

Outputs

  • System.Object

Examples

Example 1: Run the Snapshot operation

PS> Get-XenVDI -Name "Demo VDI" | Invoke-XenVDI -XenAction Snapshot -PassThru
Invokes the Snapshot operation on a VDI. -PassThru writes the result to the pipeline.

Example 2: Grow a disk that is not in use

PS> Get-XenVDI | Select-Object -First 1 |
    Invoke-XenVDI -XenAction Resize -Size 40GB
Resize is for a disk no guest is writing to. A disk can only grow; the size is in bytes, so PowerShell's GB suffix is the readable way to give it.

Example 3: Grow a disk while the VM is running

PS> Get-XenVDI | Select-Object -First 1 |
    Invoke-XenVDI -XenAction ResizeOnline -Size 60GB
Resizing a live disk is a different action rather than a flag on the same one, because it tells the storage layer the guest is using the disk while it grows. Not every storage type supports it.
  • VDI cmdlets
  • Class: VDI
  • Using the XenServer PowerShell module