CreateDifferencingVirtualHardDisk method of the Msvm_ImageManagementService class

Creates a differencing virtual hard disk (.vhd) file.

Syntax

uint32 CreateDifferencingVirtualHardDisk(
  [in]  string              Path,
  [in]  string              ParentPath,
  [out] CIM_ConcreteJob REF Job
);

Parameters

Path [in]

Type: string

A fully qualified path that specifies the location of the new file.

ParentPath [in]

Type: string

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

Job [out]

Type: CIM_ConcreteJob

A reference to the job (can be null if the task is completed).

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 used (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

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 creates a differencing virtual hard disk file. The referenced utilities can be found in Common Utilities for the Virtualization Samples.

using System;
using System.Management;

namespace HyperVSamples
{
    class CreateDiffVHD
    {
        static void CreateDifferencingVirtualHardDisk(string path, string parentPath)
        {
            ManagementScope scope = new ManagementScope(@"root\virtualization", null);
            ManagementObject imageService = Utility.GetServiceObject(scope, "Msvm_ImageManagementService");

            ManagementBaseObject inParams = imageService.GetMethodParameters("CreateDifferencingVirtualHardDisk");
            inParams["ParentPath"] = parentPath;
            inParams["Path"] = path;
            ManagementBaseObject outParams = imageService.InvokeMethod("CreateDifferencingVirtualHardDisk", inParams, null);
            if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
            {
                if (Utility.JobCompleted(outParams, scope))
                {
                    Console.WriteLine("{0} was created successfully.", inParams["Path"]);
                }
                else
                {
                    Console.WriteLine("Unable to create {0}", inParams["Path"]);
                }
            }

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

        static void Main(string[] args)
        {
            if (args != null && args.Length != 2)
            {
                Console.WriteLine("Usage: CreateDiffVHD path, parentPath");
                return;
            }
            CreateDifferencingVirtualHardDisk(args[0], args[1]);
        }
    }
}

The following VBScript example creates a differencing virtual hard disk file.

option explicit 

dim objWMIService
dim computerName
dim managementService
dim fileSystem

const JobStarting = 3
const JobRunning = 4
const JobCompleted = 7
const wmiStarted = 4096



const method = "CreateDifferencingVirtualHardDisk"

Main()

'-----------------------------------------------------------------
' Main routine
'-----------------------------------------------------------------
Sub Main()

    dim path, parentPath, computer, objArgs
    
    set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")

    computer = "."
    set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")
    set managementService = objWMIService.ExecQuery("Select * from Msvm_ImageManagementService").ItemIndex(0)

    set objArgs = WScript.Arguments
    if WScript.Arguments.Count = 2 then
       path = objArgs.Unnamed.Item(0)
       parentPath = objArgs.Unnamed.Item(1)
    else
       WScript.Echo "usage: cscript CreateDiffVHD.vbs path ParentPath"
       WScript.Quit(1)
    end if

    if ExecuteCreateDiffVHD(path, parentPath) then
       WriteLog "Done"
       WScript.Quit(0)
    else
        WriteLog "CreateDiffVHD failed"
        WScript.Quit(1)
    end if
End Sub


'-----------------------------------------------------------------
' Execute CreateDifferencingVirtualHardDisk
'-----------------------------------------------------------------
Function ExecuteCreateDiffVHD(path, parentPath)
    WriteLog Format2("Sub ExecuteCreateDiffVHD({0}, {1})",  Path, ParentPath)
    
    dim objInParam, objOutParams
    
    ExecuteCreateDiffVHD = false

    set objInParam = managementService.Methods_("CreateDifferencingVirtualHardDisk").InParameters.SpawnInstance_()
    objInParam.Path = path
    objInParam.ParentPath = parentPath

    set objOutParams = managementService.ExecMethod_("CreateDifferencingVirtualHardDisk", objInParam)

    if (WMIMethodStarted(objOutParams)) then
        if (WMIJobCompleted(objOutParams)) then
            WriteLog Format2("'{0}' was created as a differencing disk of '{1}' .", Path, ParentPath)
            ExecuteCreateDiffVHD = true
        end if
    end if

End Function


'-----------------------------------------------------------------
' Handle wmi return values
'-----------------------------------------------------------------
Function WMIMethodStarted(outParam)
    WriteLog "Function WMIMethodStarted"
    
    dim wmiStatus
    
    WMIMethodStarted = false

    if Not IsNull(outParam) then
        wmiStatus = outParam.ReturnValue

        if  wmiStatus = wmiStarted then
            WMIMethodStarted = true
        else
            WriteLog Format3("Failed to create differencing disk {0} for {1} with error {2}", Path, ParentPath, wmiStatus)
        end if
   end if

End Function



'-----------------------------------------------------------------
' Handle wmi Job object
'-----------------------------------------------------------------
Function WMIJobCompleted(outParam)
    WriteLog "Function WMIJobCompleted"
    
    dim WMIJob, jobState

    set WMIJob = objWMIService.Get(outParam.Job)

    WMIJobCompleted = true

    jobState = WMIJob.JobState

    while jobState= JobRunning or jobState = JobStarting
        WriteLog Format1("In progress... {0}% completed.",WMIJob.PercentComplete)
        WScript.Sleep(1000)
        set WMIJob = objWMIService.Get(outParam.Job)
        jobState = WMIJob.JobState
    wend

    if (jobState <> JobCompleted) then
        WriteLog Format1("ErrorCode:{0}", WMIJob.ErrorCode)
        WriteLog Format1("ErrorDescription:{0}", WMIJob.ErrorDescription)
        WMIJobCompleted = false
    end if

End Function

'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
    dim fileStream
    set fileStream = fileSystem.OpenTextFile(".\CreateDiffVHD.log", 8, true)
    WScript.Echo line
    fileStream.WriteLine line
    fileStream.Close

End Sub

'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format3(myString, arg0, arg1, arg2)

    Format3 = Format2(myString, arg0, arg1)
    Format3 = Replace(Format3, "{2}", arg2)

End Function

'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
    Format2 = Format1(myString, arg0)
    Format2 = Replace(Format2, "{1}", arg1)
End Function

'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
    Format1 = Replace(myString, "{0}", arg0)
End Function

Requirements

See also

CreateVirtualHardDisk (V2)

CIM_ConcreteJob

Msvm_ImageManagementService