Skip to content
This repository has been archived by the owner on Jul 29, 2024. It is now read-only.
/ HyperV.NET Public archive

Simple Hyper-V Virtual Machine Management

License

Notifications You must be signed in to change notification settings

jscarle/HyperV.NET

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

45 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HyperV.NET - Simple Hyper-V Virtual Machine Management

The primary design goal of the HyperV.NET library is to abstract Hyper-V's WMI provider and present a simplified and strongly typed .NET implementation for managing Hyper-V Virtual Machines. Much of the underlying mechanics have therefore purposefully been abstracted behind private or internal modifiers.

nuget master develop

References

This library targets .NET Framework 4.5 and 5.0 and references the System and System.Management namespaces only.

Supported Generations

Only Generation 2 virtual machines can be created.

Compatiblity Testing

This has only been tested on Windows Server 2016 and Windows Server 2019 at the moment.

Quick Start

Connecting to Virtual Machine Management Service

VMMS vmms = new VMMS("hostname");

Creating a new Virtual Machine

// Define the Virtual Machine
VirtualMachineDefinition virtualMachineDefinition = new VirtualMachineDefinition(
    "vmname",
    @"C:\ProgramData\Microsoft\Windows\Hyper-V"
);
virtualMachineDefinition.Memory.Startup = 4096;
virtualMachineDefinition.Processor.Quantity = 2;
virtualMachineDefinition.ScsiControllers[0].Drives[0] = new VirtualHardDrive(new VirtualHardDisk(
    VirtualHardDiskFormat.Vhdx,
    VirtualHardDiskType.FixedSize,
    64,
    @"C:\Users\Public\Documents\Hyper-V\Virtual Hard Disks\vmname.vhdx"
));
virtualMachineDefinition.ScsiControllers[0].Drives[1] = new VirtualDvdDrive();
virtualMachineDefinition.NetworkAdapters[0].VirtualSwitch = "VM Switch Name";
virtualMachineDefinition.AutomaticStop.Action = AutomaticStopAction.Shutdown;

// Create the Virtual Machine
vmms.CreateVirtualMachine(virtualMachineDefinition);

Reordering the Boot Order

// Get boot order
BootEntries bootOrder = vmms.GetVirtualMachineBootOrder(virtualMachineDefinition.Name);

// Rearrange boot order
BootEntries newBootOrder = new BootEntries();
newBootOrder.AddRange(bootOrder.Where(bootDevice => bootDevice.DeviceType == BootDeviceType.DvdDrive));
newBootOrder.AddRange(bootOrder.Where(bootDevice => bootDevice.DeviceType == BootDeviceType.File));
newBootOrder.AddRange(bootOrder.Where(bootDevice => bootDevice.DeviceType == BootDeviceType.HardDrive));
newBootOrder.AddRange(bootOrder.Where(bootDevice => bootDevice.DeviceType == BootDeviceType.NetworkAdapter));
newBootOrder.AddRange(bootOrder.Where(bootDevice => bootDevice.DeviceType == BootDeviceType.Unknown));

// Set new boot order
vmms.SetVirtualMachineBootOrder(virtualMachineDefinition.Name, newBootOrder);

Getting and changing the Virtual Machine's state

// Get current state of virtual machine
VirtualMachineState state = vmms.GetVirtualMachineState(virtualMachine.Name);

// If the virtual machine is running, shut it down
if (state == VirtualMachineState.Running)
    vmms.ShutDownVirtualMachine(virtualMachine.Name);

// Alternatively, turn off the Virtual Machine
vmms.TurnOffVirtualMachine(virtualMachine.Name);

Deleting a Virtual Machine

// Delete the virtual machine
vmms.DeleteVirtualMachine("vmname");

Mentions

Developing this library would not have been possible without some important resources.

At least there is some documentation of the Hyper-V WMI provider. It is very sparsely documented and as a result I banged my head against the wall several times trying to put this together. Nevertheless, it is the golden resource.

WMI Explorer is an excellent tool and allowed me to fill the gaps in the aformentioned documentation.

Using a combination of Stephane Thirion's post discussing the issue with the Add-VMTPM Powershell Cmdlet and Luís Henrique Demetrio's useful tidbit on how to get the source code of Powershell Cmdlets using ILspy, I was finally able to get the security settings to work through WMI. The error messages are about as helpful as the documentation!

Configurable Settings

Nearly all of the configurable settings found in the standard Hyper-V management interface are available when creating a new virtual machine using this library. The following table describes which settings from that dialog can be configured.

Setting Available Notes
General
Name ✔️ Yes
Notes ✔️ Yes
Configuration Path ✔️ Yes
Add Hardware
SCSI Controller ✔️ Yes ℹ️ Up to 4 SCSI Controllers can be added.
Network Adapter ✔️ Yes ℹ️ Up to 8 Network Adapters can be added.
RemoteFX 3D Video Adapter ❌ No
Fibre Channel Adapter ❌ No
Firmware
Boot Order ✔️ Yes ℹ️ Can be configured after the virtual machine is created.
Security
Secure Boot ✔️ Yes
Secure Boot Template ✔️ Yes
Trusted Platform Module ✔️ Yes
Encrypt Traffic ✔️ Yes
Shielding ✔️ Yes
Memory
Startup RAM ✔️ Yes
Dynamic Memory ✔️ Yes
Minimum RAM ✔️ Yes
Maximum RAM ✔️ Yes
Memory Buffer ✔️ Yes
Memory Weight ✔️ Yes
Processor
Number of Processors ✔️ Yes
Processor Reservation ✔️ Yes
Processor Limit ✔️ Yes
Processor Weight ✔️ Yes
Processor Compatibility ✔️ Yes
NUMA Topology: Processors ✔️ Yes
NUMA Topology: Memory ✔️ Yes
NUMA Topology: Nodes ✔️ Yes
Hardware Threads per Core ✔️ Yes ℹ️ Requires configuration version 8.0 or higher.
SCSI Controller ℹ️ Up to 64 devices per SCSI Controller can be added.
Hard Drive
Controller ✔️ Yes
Location ✔️ Yes
Media: Virtual Hard Disk ✔️ Yes
Media: Physical Hard Disk ❌ No
Quality of Service ✔️ Yes
Minimum IOPS ✔️ Yes
Maximum IOPS ✔️ Yes
Policy ❌ No
Virtual Hard Disk
Format ✔️ Yes
Type ⚠️ Partial ℹ️ Differencing Disks are not supported.
Size ✔️ Yes
Path ✔️ Yes
DVD Drive
Controller ✔️ Yes
Location ✔️ Yes
Media: Path ✔️ Yes
Network Adapter
Virtual Switch ✔️ Yes
VLAN ✔️ Yes
VLAN ID ✔️ Yes
Bandwidth Management ✔️ Yes
Minimum Bandwidth ✔️ Yes
Maximum Bandwidth ✔️ Yes
Virtual Machine Queue ✔️ Yes
IPsec Task Offloading ✔️ Yes
Maximum Offloaded SA ✔️ Yes
SR-IOV ✔️ Yes
Dynamic MAC Address ✔️ Yes
Static MAC Address ✔️ Yes
MAC Address Spoofing ✔️ Yes
DHCP Guard ✔️ Yes
Router Guard ✔️ Yes
Protected Network ✔️ Yes
Port Mirroring ✔️ Yes
NIC Teaming ✔️ Yes
Device Naming ✔️ Yes
Integration Services
Operating System Shutdown ✔️ Yes
Time Synchronization ✔️ Yes
Data Exchange ✔️ Yes
Heartbeat ✔️ Yes
Backup (Volume Shadow Copy) ✔️ Yes
Guest Services ✔️ Yes
Checkpoints
Enable ✔️ Yes
Production ✔️ Yes
Fallback ✔️ Yes
Standard ✔️ Yes
Path ✔️ Yes
Smart Paging
Path ✔️ Yes
Automatic Start
Action ✔️ Yes
Delay ✔️ Yes
Automatic Stop
Action ✔️ Yes