Import-XenMetadata

Last published : Nov 12, 2026
Uploads data to the server using the 'put\_import\_metadata' HTTP interface.
Related information
File transfer cmdlets

Syntax

Import-XenMetadata -XenHost <string> -Path <string>
    [-ProgressDelegate <HTTP.UpdateProgressDelegate>] [-Restore <bool>] [-Force <bool>]
    [-DryRun <bool>] [-CancellingDelegate <HTTP.FuncBool>] [-TimeoutMs <int>]
    [-Proxy <IWebProxy>]
    [-CertificateValidationCallback <RemoteCertificateValidationCallback>]
    [-NoWarnNewCertificates] [-NoWarnCertificates] [-TaskRef <string>] [-BestEffort]
    [-SessionOpaqueRef <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

This cmdlet wraps the 'put\_import\_metadata' HTTP interface of the server. Uploads data to the server over HTTP(S).

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

-CancellingDelegate

A delegate polled during the transfer; returning true cancels it.
Attribute Value
Type HTTP.FuncBool
Required False
Position Named
Accepts pipeline input False

-CertificateValidationCallback

A callback used to validate the server's TLS certificate.
Attribute Value
Type RemoteCertificateValidationCallback
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

-DryRun

If true, checks the metadata against the pool and reports the result without importing anything.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-Force

If true, the import continues past checks that would otherwise fail it: with -Restore, an export no newer than the existing VM still replaces it, and a running VM that would be replaced is skipped rather than failing the import.
Attribute Value
Type bool
Required False
Position Named
Accepts pipeline input False

-NoWarnCertificates

If set, no warning is issued for certificate validation failures.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-NoWarnNewCertificates

If set, no warning is issued when the server presents a certificate that has not been seen before.
Attribute Value
Type SwitchParameter
Required False
Position Named
Accepts pipeline input False

-Path

The path of the local file to read from or write to.
Attribute Value
Type string
Required True
Position Named
Accepts pipeline input False

-ProgressDelegate

A delegate called with the progress of the upload.
Attribute Value
Type HTTP.UpdateProgressDelegate
Required False
Position Named
Accepts pipeline input False

-Proxy

The web proxy to use for the request.
Attribute Value
Type IWebProxy
Required False
Position Named
Accepts pipeline input False

-Restore

If true, the VM keeps the UUID it was exported with, replacing any existing VM with that UUID. The existing VM must be halted and older than the one imported, unless -Force is set.
Attribute Value
Type bool
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

-TaskRef

The opaque reference of a task to track the transfer with.
Attribute Value
Type string
Required False
Position Named
Accepts pipeline input False

-TimeoutMs

The timeout of the HTTP request, in milliseconds.
Attribute Value
Type int
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

-XenHost

The address of the server to transfer data with.
Attribute Value
Type string
Required True
Position Named
Accepts pipeline input False

Inputs

  • None

Outputs

  • void

Examples

Example 1: Upload a file to the server

PS> Import-XenMetadata -XenHost "myserver" -Path "C:\upload.dat"
Uploads the contents of the local file to the server.

Example 2: Set a timeout for the transfer

PS> Import-XenMetadata -XenHost "myserver" -Path "C:\upload.dat" -TimeoutMs 600000
Gives the transfer ten minutes. The timeout covers the HTTP request, not the API call that set it up.

Example 3: Use an existing session

PS> Import-XenMetadata -XenHost "myserver" -Path "C:\upload.dat" -SessionOpaqueRef $session.opaque_ref
Runs against a session already opened with Connect-XenServer rather than the default one, which is how a script drives more than one server at a time.