MergeVirtualHardDisk method of the Msvm_ImageManagementService class

Article
01/07/2021

Merges a child virtual hard disk in a differencing chain with one or more parent virtual hard disks in the chain. See Remarks for usage restrictions for this method.

If the user executing this function does not have permission to update the virtual machines, then this function will fail.

Syntax

uint32 MergeVirtualHardDisk(
  [in]  string              SourcePath,
  [in]  string              DestinationPath,
  [out] CIM_ConcreteJob REF Job
);

Parameters

SourcePath [in]

Type: string

A fully qualified path that specifies the location of the virtual hard disk file to merge.

DestinationPath [in]

Type: string

A fully qualified path that specifies the location of the parent virtual hard disk file into which data is to be merged. This could be the immediate parent virtual hard disk of the merging file or the parent disk image a few levels up the differencing chain.

Job [out]

Type: CIM_ConcreteJob

If the operation is performed asynchronously, this method will return 4096, and this parameter will contain a reference to an object derived from CIM_ConcreteJob.

Return value

Type: uint32

This method can return one of the following values.

Completed with No Error (0)
Method Parameters Checked - Job Started (4096)
Failed (32768)
Access Denied (32769)
Not Supported (32770)
Status is unknown (32771)
Timeout (32772)
Invalid parameter (32773)
System is in use (32774)
Invalid state for this operation (32775)
Incorrect data type (32776)
System is not available (32777)
Out of memory (32778)
File not found (32779)

Remarks

The child virtual hard disk must be offline.

Only the following types of virtual hard disks can be used with this method:

Differencing VHD
Differencing VHDX

Access to the Msvm_ImageManagementService class might be restricted by UAC Filtering. For more information, see User Account Control and WMI.

Examples

The following C# example expands a virtual hard disk file. The referenced utilities can be found in Common utilities for the virtualization samples (V2).

// Merges a VHD into a parent VHD.
// ChildPath: The path to the VHD to merge.</param>
// ParentPath: The path to the parent into which to merge.</param>
public static void MergeVirtualHardDisk(string ChildPath, string ParentPath)
{
    ManagementScope scope = new ManagementScope(@"root\virtualization\v2", null);
    ManagementObject imageService = Utility.GetServiceObject(scope, "Msvm_ImageManagementService");

    ManagementBaseObject inParams = imageService.GetMethodParameters("MergeVirtualHardDisk");

    inParams["SourcePath"] = ChildPath;
    inParams["DestinationPath"] = ParentPath;

    ManagementBaseObject outParams = imageService.InvokeMethod("MergeVirtualHardDisk", inParams, null);

    if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
    {
        if (Utility.JobCompleted(outParams, scope))
        {
            Console.WriteLine("MergeVirtualHardDisk succeeded.");
        }
        else
        {
            Console.WriteLine("MergeVirtualHardDisk failed.");
        }
    }

    outParams.Dispose();
    inParams.Dispose();
    imageService.Dispose();
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Namespace	Root\Virtualization\V2
MOF	WindowsVirtualization.V2.mof
DLL	Vmms.exe

Share via