This sample demonstrates how to use the Hyper-V WMI APIs and Virtual Hard Disk APIs to manage virtual hard disks.

The Windows Samples Gallery contains a variety of code samples that demonstrate the use of various new programming features for managing Hyper-V that are available in Windows 8 and/or Windows Server 2012. These downloadable samples are provided as compressed ZIP files that contain a Microsoft Visual Studio 2010 solution (SLN) file for the sample, along with the source files, assets, resources, and metadata necessary to successfully compile and run the sample. For more information about the programming models, platforms, languages, and APIs demonstrated in this sample, please refer to the Hyper-V WMI provider (V2) documentation.

To obtain an evaluation copy of Windows 8, go to Windows 8.

Related technologies

Hyper-V WMI provider (V2), Virtual Storage

Operating system requirements

Client
Windows 8
Server
Windows Server 2012

Build the sample

Building the C# version of the sample

  1. Start Visual Studio and select File > Open > Project/Solution.

  2. Go to the directory in which you unzipped the sample. Go to the directory named for the sample, and double-click the Microsoft Visual Studio Solution (.sln) file titled Storage.sln from Visual Studio 2010.

  3. Press F7 (or F6 for Microsoft Visual Studio Ultimate 2012) or use Build > Build Solution to build the sample.

Building the C++ version of the sample

  1. Start Visual Studio 2010 and select File > Open > Project/Solution.

  2. Go to the directory in which you unzipped the sample. Go to the directory named for the sample, and double-click the Microsoft Visual Studio Solution (.sln) file titled Storage.sln.

  3. Press F7 (or F6 for Visual Studio Ultimate 2012) or use Build > Build Solution to build the sample.

Run the sample

Running the C# version of the sample

Note  This sample must be run as an administrator.

This sample is written in C# using the Hyper-V WMI APIs, and requires some experience with WMI programming.

This sample can be run in several different modes.

Retrieve information about a virtual hard disk

To retrieve information about a virtual hard disk using the GetVirtualHardDiskSettingData and GetVirtualHardDiskState methods, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe GetVirtualHardDisk ServerName VhdPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Modify the settings of a virtual hard disk

To modify the settings of a virtual hard disk using the SetVirtualHardDiskSettingData method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe SetVirtualHardDisk ServerName VhdPath ParentPath Format FileSize BlockSize SectorSize

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file to be modified.
    • ParentPath is the new path of the parent virtual hard disk file.
    • Format is "vhdx" to make the virtual hard disk a VHDX or "vhd" to make the virtual hard disk a VHD.
    • FileSize is the new maximum size of the virtual hard disk, in bytes.
    • BlockSize is the new block size of the virtual hard disk, in bytes.
    • SectorSize is the new sector size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Validate a virtual hard disk

To validate a virtual hard disk using the ValidateVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe ValidateVirtualHardDisk ServerName VhdPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a fixed virtual hard disk

To create a fixed virtual hard disk using the CreateVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe CreateFixedVirtualHardDisk ServerName VhdPath Format FileSize BlockSize SectorSize

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file to be created.
    • Format is "vhdx" to make the new virtual hard disk a VHDX or "vhd" to make the new virtual hard disk a VHD.
    • FileSize is the maximum size of the virtual hard disk, in bytes.
    • BlockSize is the block size of the virtual hard disk, in bytes.
    • SectorSize is the sector size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a dynamic virtual hard disk

To create a dynamic virtual hard disk using the CreateVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe CreateDynamicVirtualHardDisk ServerName VhdPath Format FileSize BlockSize SectorSize

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file to be created.
    • Format is "vhdx" to make the new virtual hard disk a VHDX or "vhd" to make the new virtual hard disk a VHD.
    • FileSize is the initial maximum size of the virtual hard disk, in bytes.
    • BlockSize is the block size of the virtual hard disk, in bytes.
    • SectorSize is the sector size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a differencing virtual hard disk

To create a differencing virtual hard disk using the CreateVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe CreateDifferencingVirtualHardDisk ServerName VhdPath ParentPath Format

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the new virtual hard disk file.
    • ParentPath is the path of the parent virtual hard disk file.
    • Format is "vhdx" to make the new virtual hard disk a VHDX or "vhd" to make the new virtual hard disk a VHD.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a virtual floppy disk

To create a virtual floppy disk using the CreateVirtualFloppyDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe CreateVirtualFloppyDisk ServerName VhdPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Attach a virtual hard disk

To attach a virtual hard disk using the AttachVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe AttachVirtualHardDisk ServerName VhdPath AssignDriveLetter ReadOnly

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file to be attached.
    • AssignDriveLetter is "True" to automatically assign a drive letter to the attached drive or "False" otherwise.
    • ReadOnly is "True" to make the attached drive read only or "False" otherwise.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Detach a virtual hard disk

To detach a virtual hard disk using the DetachVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe DetachVirtualHardDisk ServerName VhdPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Update the parent of a virtual hard disk

To update the parent of a virtual hard disk using the SetParentVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe SetParentVirtualHardDisk ServerName ChildPath ParentPath LeafPath IgnoreIDMistmatch

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • ChildPath is the path of the child virtual hard disk file.
    • ParentPath is the path of the parent virtual hard disk file.
    • LeafPath is the path of the leaf virtual hard disk file.
    • IgnoreIDMistmatch is "True" to forcibly set the parent even if the identifiers do not match, or "False" otherwise.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Convert a virtual hard disk to fixed

To convert a non-fixed virtual hard disk to fixed using the ConvertVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe ConvertVirtualHardDisk ServerName VhdSourcePath VhdDestinationPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdSourcePath is the path of the virtual hard disk file to be converted.
    • VhdDestinationPath is the destination path of the converted virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Merge a virtual hard disk

To merge a virtual hard disk using the MergeVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe MergeVirtualHardDisk ServerName VhdSourcePath VhdDestinationPath

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdSourcePath is the path of the virtual hard disk file to be merged.
    • VhdDestinationPath is the destination path of the merged virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Compact a virtual hard disk

To compact a virtual hard disk using the CompactVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe CompactVirtualHardDisk ServerName VhdPath Mode

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file.
    • Mode specifies the compaction mode and is one of the numeric values specified for the Mode parameter of the CompactVirtualHardDisk method.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Resize a virtual hard disk

To resize a virtual hard disk using the ResizeVirtualHardDisk method, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    StorageSamplesWmi.exe ResizeVirtualHardDisk ServerName VhdPath NewSize

    where the parameters are as follows:

    • ServerName is the name of the server on which to perform the operation.
    • VhdPath is the path of the virtual hard disk file to be resized.
    • NewSize is the new maximum size of virtual hard disk file, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Running the C++ version of the sample

Note  This sample must be run as an administrator.

This sample is written in C++ using the Virtual Storage APIs and requires some experience with Windows API programming.

The sample demonstrates how to perform each of the following operations:

Retrieve information about a virtual hard disk

To retrieve information about a virtual hard disk using the GetVirtualDiskInformation function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe GetVirtualDiskInformation VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a fixed virtual hard disk

To create a fixed virtual hard disk using the CreateVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe CreateFixedVirtualDisk VhdPath FileSize BlockSize SectorSize

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • FileSize is the maximum size of the virtual hard disk.
    • BlockSize is the block size of the virtual hard disk, in bytes.
    • SectorSize is the sector size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a dynamic virtual hard disk

To create a dynamic virtual hard disk using the CreateVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe CreateDynamicVirtualDisk VhdPath FileSize BlockSize SectorSize

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • FileSize is the initial maximum size of the virtual hard disk.
    • BlockSize is the block size of the virtual hard disk, in bytes.
    • SectorSize is the sector size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Create a differencing virtual hard disk

To create a differencing virtual hard disk using the CreateVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe CreateDifferencingVirtualDisk VhdPath ParentPath

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • ParentPath is the path of the parent virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Attach a virtual hard disk

To attach a virtual hard disk using the AttachVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe AttachVirtualDisk VhdPath ReadOnly

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • ReadOnly is "True" to make the attached drive read only or "False" otherwise.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Detach a virtual hard disk

To detach a virtual hard disk using the DetachVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe DetachVirtualDisk VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Update information about a virtual hard disk

To update information about a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe SetVirtualDiskInformation VhdPath ParentPath PhysicalSectorSize

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • ParentPath is the path of the parent virtual hard disk file.
    • PhysicalSectorSize is the new physical sector size, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Merge a virtual hard disk

To merge a virtual hard disk using the MergeVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe MergeVirtualDisk VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Compact a virtual hard disk

To compact a virtual hard disk using the CompactVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe CompactVirtualDisk VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Resize a virtual hard disk

To resize a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe ResizeVirtualDisk VhdPath FileSize

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • FileSize is the new maximum size of the virtual hard disk, in bytes.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Mirror a virtual hard disk

To mirror a virtual hard disk using the MirrorVirtualDisk function, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe MirrorVirtualDisk SourcePath DestinationPath

    where the parameters are as follows:

    • SourcePath is the path of the source virtual hard disk file.
    • DestinationPath is the path of the destination virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Enumerate user metadata for a virtual hard disk

To enumerate user metadata for a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe EnumerateUserMetaData VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Update user metadata for a virtual hard disk

To update user metadata for a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe SetUserMetaData VhdPath ID

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • ID is the new identifier for the virtual hard disk.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Obtain user metadata for a virtual hard disk

To obtain user metadata for a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe GetUserMetaData VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Delete user metadata for a virtual hard disk

To obtain user metadata for a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe DeleteUserMetaData VhdPath

    where VhdPath is the path of the virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.

Add a parent to a virtual hard disk

To add a parent to a virtual hard disk, follow these steps.

  1. Enter the debug command line arguments for the project. The usage of this sample is:

    Storage.exe AddVirtualDiskParent VhdPath ParentPath

    where the parameters are as follows:

    • VhdPath is the path of the virtual hard disk file.
    • ParentPath is the path of the parent virtual hard disk file.

  2. To debug the app and then run it from Visual Studio 2010, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.

  3. The final result of the operation will be displayed in the console window.