Hyper-V and PowerShell: VM Process

In the article that contains the Restart-VM script, I mentioned that a VM that can’t be stopped with Stop-VM requires you to kill its VMWP process. It might not be obvious how to determine which process that is. I’ve written a script to help you do that.

This article is part of the “Hyper-V and PowerShell” series.

This script is extremely straightforward so it doesn’t require a lot of explanation. I opted to only allow you to input a single VM name at a time. If you use the pipeline, it will run once for each input object as normal.

As with the Restart-VM script, I designed this one as a function that must be dot-sourced. Please read that article for directions.

Parameters

There are only three parameters: Name, ComputerName, and VM.

Name: The name of the virtual machine whose process you wish to retrieve. Cannot be used with VM.

ComputerName: The name of the Hyper-V computer that hosts the virtual machine. Cannot be used with VM.

VM: The VM object whose process you wish to retrieve. Cannot be used with Name or ComputerName.

The Script

Copy the contents of the following block and save it as a .PS1 file. It was written with the expectation that you would name it Get-VMProcess, but that’s not required. You can only operate it with Get-VMProcess without modifying the file, though.

#requires -Version 3
#requires -Modules Hyper-V

function Get-VMProcess
{
	<#
	.SYNOPSIS
	Retrieves the VM worker process (VMWP) that is the container for a virtual machine.

	.DESCRIPTION
	VMWP.EXE is the process that Hyper-V uses to control its guests. Each virtual machine has its own, and they are visible in the mangaement operating system.

	This function retrieves the VMWP process for a specific virtual machine. You can then pipe it to Stop-Process if you need to shut down an unresponsive VM.

	.PARAMETER Name
	The name of the virtual machine to retrieve the worker process for. Cannot be used with -VM.

	.PARAMETER ComputerName
	The name of the Hyper-V host that runs the VM to be scanned for. If not specified, the local machine will be used.
	Cannot be used with -VM.

	.PARAMETER VM
	A virtual machine object to retrieve the worker process for. Cannot be used with -Name or -ComputerName.

	.OUTPUTS
	System.Diagnostics.Process

	.NOTES
	    Author: Eric Siron
	    Copyright: (C) 2014 Altaro Software
	    Version 1.0
	    Authored Date: November 15, 2014

	.LINK
	    
Hyper-V and PowerShell: VM Process


	.EXAMPLE
		C:\PS> Get-VMProcess svhungsystem

		Description
		-----------
		Retrieves the VMWP process for the virtual machine name svhungsystem on the local computer.

	.EXAMPLE
		C:\PS> Get-VM svhungsystem | Get-VMProcess

		Description
		-----------
		Retrieves the VMWP process for the virtual machine name svhungsystem on the local computer.

	.EXAMPLE
		C:\PS> Get-VMProcess -Name svhungsystem | Stop-Process -Force

		Description
		-----------
		Forcefully stops the VMWP process containing the virtual machine named svhungsystem.
	#>

	[CmdletBinding()]
	param(
		[Alias("VMName")]
		[Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true, ParameterSetName='ByName', Mandatory=$true, Position=1)]
		[String]$Name,

		[Alias("VMHost")]
		[Parameter(ValueFromPipelineByPropertyName=$true, Position=2, ParameterSetName='ByName')]
		[String]$ComputerName = $env:COMPUTERNAME,

		[Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true, ParameterSetName='ByVM')]
		[Microsoft.HyperV.PowerShell.VirtualMachine]$VM
	)

	BEGIN {}
	PROCESS {
		if($VM)
		{
			$VMId = $VM.VMId
			$ComputerName = $VM.ComputerName
		}
		else
		{
			$VMId = (Get-VM -Name $Name -ComputerName $ComputerName -ErrorAction Stop).VMId
		}
		if($VMId)
		{
			$ProcessID = (Get-WmiObject -ComputerName $ComputerName -Namespace root\virtualization\v2 -Class Msvm_ComputerSystem -Filter "Name = '$VMId'").ProcessID
			if($ProcessID)
			{
				Get-Process -ComputerName $ComputerName -Id $ProcessID
			}
		}
	}
	END {}
}

Uses

I suppose there are any number of reasons you might want to use this script, but I mostly assumed it would be for the purposes of stopping a hung virtual machine. As shown in the help, you can use this with Stop-Process:

Get-VMProcess -Name svhungsystem | Stop-Process -Force

Warning

This is probably obvious, but stopping a virtual machine with Stop-Process like this should be considered a last resort. There’s nothing graceful about it and data loss is likely to occur. Please exhaust all other methods before trying this VM process.