Class HyperVClient

Abstracts management of local Hyper-V virtual machines and components on Windows via PowerShell.

note

This class requires elevated administrative rights.

Inheritance

object

HyperVClient

Namespace: Neon.HyperV

Assembly: Neon.HyperV.dll

Syntax

public class HyperVClient

Constructors

HyperVClient(HyperVDriverType)

Default constructor to be used to manage Hyper-V objects on the local Windows machine.

Declaration

public HyperVClient(HyperVDriverType driverType = HyperVDriverType.Wmi)

Parameters

Type	Name	Description
HyperVDriverType	driverType	Optionally overrides the default Hyper-V driver implementation. This defaults to Wmi and is generally overridden only by unit tests.

Properties

DefaultDriveFolder

Returns the path to the user's default Hyper-V virtual drive folder.

Declaration

public static string DefaultDriveFolder { get; }

Property Value

Type	Description
string

IsNestedVirtualization

Determines whether the current machine is already running as a Hyper-V virtual machine and that any Hyper-V VMs deployed on this machine can be considered to be nested.

Declaration

public bool IsNestedVirtualization { get; }

Property Value

Type	Description
bool

Remarks

We use the presence of this registry value to detect VM nesting:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Virtual Machine\Auto\OSName

Methods

AddVm(string, string, int, string, string, bool, string, string, IEnumerable<VirtualDrive>)

Creates a virtual machine.

Declaration

public void AddVm(string machineName, string memorySize = "2GiB", int processorCount = 4, string driveSize = null, string drivePath = null, bool checkpointDrives = false, string templateDrivePath = null, string switchName = null, IEnumerable<VirtualDrive> extraDrives = null)

Parameters

Type	Name	Description
string	machineName	The machine name.
string	memorySize	A string specifying the memory size. This can be a long byte count or a byte count or a number with units like 512MiB, 0.5GiB, 2GiB, or 1TiB. This defaults to 2GiB.
int	processorCount	The number of virutal processors to assign to the machine. This defaults to 4.
string	driveSize	A string specifying the primary disk size. This can be a long byte count or a byte count or a number with units like 512MB, 0.5GiB, 2GiB, or 1TiB. Pass null to leave the disk alone. This defaults to null.
string	drivePath	Optionally specifies the path where the virtual hard drive will be located. Pass null or empty to default to MACHINE-NAME.vhdx located in the default Hyper-V virtual machine drive folder.
bool	checkpointDrives	Optionally enables drive checkpoints. This defaults to false.
string	templateDrivePath	If this is specified and drivePath is not null then the hard drive template at templateDrivePath will be copied to drivePath before creating the machine.
string	switchName	Optional name of the virtual switch.
IEnumerable<VirtualDrive>	extraDrives	Optionally specifies any additional virtual drives to be created and then attached to the new virtual machine.

Remarks

note

The Path property of extraDrives may be passed as null or empty. In this case, the drive location will default to being located in the standard Hyper-V virtual drivers folder and will be named MACHINE-NAME-#.vhdx, where # is the one-based index of the drive in the enumeration.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

AddVmDrive(string, VirtualDrive)

Creates a new virtual drive and adds it to a virtual machine.

Declaration

public void AddVmDrive(string machineName, VirtualDrive drive)

Parameters

Type	Name	Description
string	machineName	The target virtual machine name.
VirtualDrive	drive	The new drive information.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

CompactDrive(string)

Compacts a dynamic VHD or VHDX virtual disk file.

note

The disk may be mounted to a VM but the VM cannot be running.

Declaration

public void CompactDrive(string drivePath)

Parameters

Type	Name	Description
string	drivePath	Path to the virtual drive file.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

Dispose()

Releases all resources associated with the instance.

Declaration

public void Dispose()

Dispose(bool)

Releases all associated resources.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Pass true if we're disposing, false if we're finalizing.

EjectVmDvd(string)

Ejects any DVD that's currently inserted into a virtual machine.

Declaration

public void EjectVmDvd(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

FindIPAddress(string)

Returns information about a virtual IP address.

Declaration

public VirtualIPAddress FindIPAddress(string address)

Parameters

Type	Name	Description
string	address	The desired IP address.

Returns

Type	Description
VirtualIPAddress	The VirtualIPAddress or null when it doesn't exist.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

FindNatByName(string)

Looks for a virtual NAT by name.

Declaration

public VirtualNat FindNatByName(string natName)

Parameters

Type	Name	Description
string	natName	The desired NAT name.

Returns

Type	Description
VirtualNat	The VirtualNat or null if the NAT doesn't exist.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

FindNatBySubnet(string)

Looks for a virtual NAT by subnet.

Declaration

public VirtualNat FindNatBySubnet(string subnet)

Parameters

Type	Name	Description
string	subnet	The desired NAT subnet.

Returns

Type	Description
VirtualNat	The VirtualNat or null if the NAT doesn't exist.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

FindSwitch(string)

Returns information for a Hyper-V switch by name.

Declaration

public VirtualSwitch FindSwitch(string switchName)

Parameters

Type	Name	Description
string	switchName	The switch name.

Returns

Type	Description
VirtualSwitch	The VirtualSwitch when present or null.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

FindVm(string)

Gets the current status for a named virtual machine.

Declaration

public VirtualMachine FindVm(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Returns

Type	Description
VirtualMachine	The VirtualMachine or null when the virtual machine doesn't exist.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

InsertVmDvd(string, string)

Inserts an ISO file as the DVD for a virtual machine, ejecting any existing disc first.

Declaration

public void InsertVmDvd(string machineName, string isoPath)

Parameters

Type	Name	Description
string	machineName	The machine name.
string	isoPath	Path to the DVD ISO file.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

ListIPAddresses()

Lists the virtual IPv4 addresses managed by Hyper-V.

note

Only IPv4 addresses are returned. IPv6 and any other address types will be ignored.

Declaration

public IEnumerable<VirtualIPAddress> ListIPAddresses()

Returns

Type	Description
IEnumerable<VirtualIPAddress>	A list of VirtualIPAddress.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

ListNats()

Lists the virtual NATs.

Declaration

public IEnumerable<VirtualNat> ListNats()

Returns

Type	Description
IEnumerable<VirtualNat>	A list of VirtualNat.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

ListSwitches()

Lists the virtual switches.

Declaration

public IEnumerable<VirtualSwitch> ListSwitches()

Returns

Type	Description
IEnumerable<VirtualSwitch>	The switches.

ListVmDrives(string)

Returns host file system paths to any virtual drives attached to a virtual machine.

Declaration

public IEnumerable<string> ListVmDrives(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Returns

Type	Description
IEnumerable<string>	The list of fully qualified virtual drive file paths.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

ListVmNetworkAdapters(string)

Returns the virtual network adapters attached to the named virtual machine.

Declaration

public IEnumerable<VirtualMachineNetworkAdapter> ListVmNetworkAdapters(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Returns

Type	Description
IEnumerable<VirtualMachineNetworkAdapter>	The list of network adapters.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

ListVms()

Lists the virtual machines.

Declaration

public IEnumerable<VirtualMachine> ListVms()

Returns

Type	Description
IEnumerable<VirtualMachine>	IEnumerable<T>.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

NewExternalSwitch(string, IPAddress)

Adds a virtual Hyper-V switch that has external connectivity.

Declaration

public void NewExternalSwitch(string switchName, IPAddress gateway)

Parameters

Type	Name	Description
string	switchName	The new switch name.
IPAddress	gateway	Address of the LAN gateway, used to identify the connected network interface.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

NewInternalSwitch(string, NetworkCidr, bool)

Adds an internal Hyper-V switch configured for the specified subnet and gateway as well as an optional NAT enabling external connectivity.

Declaration

public void NewInternalSwitch(string switchName, NetworkCidr subnet, bool addNat = false)

Parameters

Type	Name	Description
string	switchName	The new switch name.
NetworkCidr	subnet	Specifies the internal subnet.
bool	addNat	Optionally configure a NAT to support external routing.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

RemoveSwitch(string, bool)

Removes a named virtual switch, if it exists as well as any associated NAT (with the same name).

Declaration

public void RemoveSwitch(string switchName, bool ignoreMissing = false)

Parameters

Type	Name	Description
string	switchName	The target switch name.
bool	ignoreMissing	Optionally ignore missing items.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

RemoveVm(string, bool)

Removes a named virtual machine and all of its drives (by default).

Declaration

public void RemoveVm(string machineName, bool keepDrives = false)

Parameters

Type	Name	Description
string	machineName	The machine name.
bool	keepDrives	Optionally retains the VM disk files.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

RemoveVmsWithPrefix(string)

Stops and removes all virtual machines whose name includes a prefix.

Declaration

public void RemoveVmsWithPrefix(string namePrefix)

Parameters

Type	Name	Description
string	namePrefix	Specifies the name prefix.

SaveVm(string)

Persists the state of a running virtual machine and then stops it. This is equivalent to hibernation for a physical machine.

Declaration

public void SaveVm(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

StartVm(string)

Starts the named virtual machine.

Declaration

public void StartVm(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

StopVm(string, bool)

Stops the named virtual machine.

Declaration

public void StopVm(string machineName, bool turnOff = false)

Parameters

Type	Name	Description
string	machineName	The machine name.
bool	turnOff	Optionally just turns the VM off without performing a graceful shutdown first. note WARNING! This could result in corruption or the the loss of unsaved data.

Exceptions

Type	Condition
HyperVException	Thrown for errors.

VmExists(string)

Determines whether a named virtual machine exists.

Declaration

public bool VmExists(string machineName)

Parameters

Type	Name	Description
string	machineName	The machine name.

Returns

Type	Description
bool	true if the machine exists.

Exceptions

Type	Condition
HyperVException	Thrown for errors.