Editing a .VMCX file

  • Article

In Windows Server 2016 we moved from using .XML for our virtual machine configuration files to using a binary format – that we call .VMCX.

There are many benefits to this – but one of the downsides is that it is no longer possible to easily edit a virtual machine configuration file that is not registered with Hyper-V.  Fortunately – we provide all the APIs you need to do this without editing the file directly.

This code sample takes a virtual machine configuration file – that is not registered with Hyper-V.  It then:

  • Loads the virtual machine into memory – without actually importing it into Hyper-V
  • Changes some settings on the virtual machine
  • Exports this changed virtual machine to a new .VMCX file

Using this method you can make any changes you need to a .VMCX file without actually having to import the virtual machine.  The key piece of information here is that when you perform a traditional import of a virtual machine you use ImportSystemDefinition to create a planned virtual machine (in memory copy) which you then realized to complete the import operation.  But if you do not want to import the virtual machine – but just want to edit it – you can modify the planned virtual machine and pass it into ExportSystemDefinition to create a new configuration file.

Cheers,
Ben

Comments

  • Anonymous
    April 19, 2017
    This is pretty cool, thanks for writing this up.Also I hate asking in something that isn't related to this blog post, but whatever happened to the HyperVBackup module you wrote back in 2014, it doesn't work on the RTM version of Server 2016. I've tried to find the documentation on the API's but couldn't find them. Any ideas?
    • Anonymous
      April 19, 2017
      This is in my (overflowing) backlog of things to fix. There were some relatively minor API changes that need to be updated in that script.
      • Anonymous
        April 20, 2017
        The comment has been removed
        • Anonymous
          April 20, 2017
          happy*
  • Anonymous
    April 19, 2017
    This is just what the doctor ordered! Thank you so much for posting this information.
  • Anonymous
    April 22, 2017
    It's important to note that ImportSystemDefinition() creates a new "vm" in msvm_plannedcomputersystem, therefore this script at the end should delete the "vm" from msvm_plannedcomputersystem.Otherwise after a while you end up with lots of "planned vms". I have learned the hard way (as Compare-VM is doing the same) and had to remove few tens of thousands of these "planned vms".Ben, importing a vm is the only way to modify .vmcx file ?Are you planning to make it possible on ExportSystemDefinition() to select which disks as part of storage are exported ? Currently CopyVmStorage=$true exports all of them. This is not always desirable.
  • Anonymous
    April 25, 2017
    When I attempt to run this script, the call to ImportSystemDefinition fails with a "File in Use" (32779) error and the Hyper-V Event Viewer log seems to indicate that the script is expecting to find a VMRS file with the same name as the *.VMCX that I'm attempting to edit using the script: %%21479424020x80070002D:\VMCX_Edit_Test\5434773A-47C8-4C87-B3FA-44F014686E0E.VMRSC:\ProgramData\Microsoft\Windows\Hyper-V\Planned Virtual Machines\45944326-588C-4CE1-B990-DD810ECB9222.VMRSAm I doing something wrong?
    • Anonymous
      April 25, 2017
      If I copy a *.VMRS file to the directory in which the *.VMCX file that I'm trying to edit exists and give it the same name as the *.VMCX file, the script works. It looks like ImportSystemDefinition requires a *.VMRS file to be present. Is there a way around this or will there always be a *.VMRS file for each VM?
      • Anonymous
        April 30, 2017
        Empty file named same with as .VMCX but with .VMRS extension should help ;-)
  • Anonymous
    August 09, 2017
    Is there any side effect to filling up the list of Msvm_PlannedComputerSystem objects from doing this?
  • Anonymous
    September 07, 2017
    I tried this for a set of files that are related to machines that show a status of "Cannot connect to virtual machine configuration storage" hoping to find the storage location. This was caused by a drive letter change. In the past, I could just edit the XML file. Now I get the same error in PowerShell and cannot determine which drive letter it expects. Is it possible to load the file WITHOUT it performing and validation?
  • Anonymous
    October 12, 2017
    Hi Ben,I am looking for removing failover cluster configuration removal from vm configuration. Which MSVV class should i refer to? I checked if i get anything in getrelated method for any VM configured in FOC using class "MSCluster_Resource", but no luck. Will you please help me here?
    • Anonymous
      October 17, 2017
      So also, I want to remove existing configurations such as vhd/vhdx file location & network configuration. Will you please help me here?