Free Script: Find Orphaned Hyper-V VM Files

If you’ve had very much virtual machine churn in your environment, it’s almost inevitable that you’ve wound up with a few disconnected virtual machine files here and there. This free script will help you to locate orphaned Hyper-V VM files. For fellow infrastructure scripters, there is a special bonus script included as well.

The worst thing about my testing environment is that I often wind up with files that look legitimate, but are no longer part of any virtual machine. Even in live environments, some virtual machine moves and operations leave a trail of unwanted files. Errors and failures can produce more.

Finding virtual machine files isn’t hard, but ensuring that they’re not really attached to something can be much more difficult than it might at first seem. I tried very hard to include a great many features to cover every scenario I could think of.

Last Updated: April 11th, 2015

Feature List

• Aware of snapshots/checkpoints
• Aware of differencing disk chains
• Cluster-aware
  • Will only scan Cluster Shared Volumes from a single node, and will not generate false positives while scanning other nodes
  • Will differentiate between shared and not shared storage, so you can scan local drives on nodes
  • Will detect all nodes in a cluster and scan each
  • Can be set to ignore cluster membership if you only want to scan non-shared locations
  • I didn’t do extensive testing with standard cluster disks as they’re not something I use, but it seems to work well enough. However, if a cluster disk were to move between the portion of the script where it scans for files to exclude and when it scans again for orphans, the results will be invalid.
  • The script understands raw volume identifiers, although I didn’t do a great deal of testing with those either.
• Can be run from any system with PowerShell 4.0; the Hyper-V module is not required. I didn’t test it with PowerShell 3.0 systems because I haven’t got any left, but I think it will work
• Can target 2012 and 2012 R2 systems simultaneously
• Options to scan one or all of the following locations: the host’s default VM and VHD paths, all paths currently in use by VMs, and paths that you specify
• All scans occur directly on the target host(s) except in the case of UNC paths, and each separate host is scanned in parallel
• Detailed built-in help. Use Get-Help -Full to see it

Files that the Script Scans For

• XML files with a base name in the format of a GUID. It does not parse the XML to see if they really are Hyper-V files, so watch out for false positives.
• BIN files with a base name in the format of a GUID.
• VSV files with a base name in the format of a GUID
• SLP files with a base name in the format of a GUID and an intermediate extension
• VHD, VHDX, AVHD, AVHDX, and VFD files; if you look at the script, it will match on anything that has VHD or VFD anywhere in the extension; please report false positives as I can update the script to be more selective if necessary.

Notes

• All target hosts must have the Hyper-V PowerShell module installed. Any that don’t have it will throw errors that they cannot be scanned. The computer that you’re using to run the script does not need anything other than the default PowerShell modules installed. However, scanning SMB shares will be considerably faster if the Hyper-V module is installed locally.
• The script will only exclude differencing disk chains from the point that a VM references it and upward to the root. For example, let’s say you have a “root.vhdx” with children “diff1.vhdx”, “diff2.vhdx”, and “diff3.vhdx”, with each one being a child of the previous disk. Let’s say you have a virtual machine that references “diff2.vhdx”. The scan will find the VM using “diff2.vhdx” and trace its chain upward through “diff1.vhdx” and “root.vhdx” and ignore them. If it doesn’t find any VM using “diff3.vhdx”, that file will be marked as orphaned. However, the script is snapshot/checkpoint aware so even complicated trees should not trigger a false positive.
• The script uses a mix of implicit and explicit PowerShell Remoting with a very heavy dependence upon explicit. Even if you initiate directly from a system to be scanned, it will use PSRemoting. The drawback is that you can’t initiate this script inside a remote session unless you have CredSSP enabled and even then it might fail. To compensate, I ensured that you don’t need to have any special modules installed on the system that you run the script from.
• You can’t specify connection credentials for scanning SMB 3 storage. I tried. It didn’t work. I didn’t get any errors to troubleshoot. It just didn’t work. If you use the -Credential parameter, the credentials will be used for retrieving host details, determining existing VM information and paths, and scanning storage local to the target hosts, but SMB 3 shares will be scanned using the credentials of the local session being used to invoke this function.
• This script uses fully-qualified domain names to connect to domain members and you can’t get around it. The purpose of this is to ensure that cluster scans work correctly. For instance, if you pass in the short name of a cluster (“clhv1” in my case), it will use WSMan to attach to that address, query the system for its FQDN using WMI, and use that for all future connections. While it’s there, it will also determine the names of any other systems in the cluster and retrieve those as well. The side effect is that if you supply a DNS alias, it will be replaced with the true computer’s name for all subsequent connections. If you’re having trouble connecting to a system, this is probably why. Use the -Verbose switch to find out what system name it’s trying to connect to. If the target isn’t domain-joined, then the script should connect using only its NetBIOS name.
• I had to install a lot of wiring to avoid returning false positives on Cluster Shared Volumes. The solution I settled on is that all scans of the ClusterStorage path will be handled only through the primary node in all cases. You won’t be able to bypass this behavior by any means, even by manually specifying a path of C: or C:ClusterStorage. I don’t think this will be a problem, but the explanation is here just in case you see behavior that you didn’t expect, such as by setting -IgnoreClusterMembership and scanning the C: drive of a node other than the primary.
• The way I use PowerShell Remoting in parallel might cause some scans to take longer than you might think they would when you are only scanning the local system. That’s because of the behavior of the Wait-Job cmdlet. Since disk scans tend to be slow anyway, I don’t think that this adds enough time to the scan to be harmful, but if you think that something is taking a few seconds longer than it should, this is probably why.
• The script will scan UNC paths, but might have some unexpected behavior in a few cases. For instance, let’s say you have a Windows Server system serving an SMB 3 share to hold VMs for other hosts. You also decide to stand up a local VM on that host and put it in the same location. From that host’s perspective, the VM might be stored in, let’s say D:VMs. D:VMs is also shared as \storage-serverVMs. If the scan is set to look at that share location, then it’s going to return all of that virtual machine’s files as orphans because it only knows them as being registered in D:VMs on that host.

There is no built-in option to remove the files that it finds. This would be a fairly trivial modification, but I’m not going to make it. I worked very hard to do almost everything I could to eliminate false positives, but they can and will happen and I won’t be responsible for someone accidentally wiping out all their templates or a completely unrelated file that happened to be named in the pattern of a Hyper-V file.

Script Usage

There are two parameter sets. The first is the default. It first finds all the virtual machines on a host for their files. It then scans all the folders that hold those files and the folders marked as the host’s defaults for orphans.

Default Parameter Set

• ComputerName accepts a string array of computer names. If you don’t include any, the local system is scanned.
• ExcludeDefaultPath prevents the host’s default paths from being scanned for orphaned files.
• ExcludeExistingVMPaths prevents the paths of existing VMs from being scanned for orphaned files.
• IgnoreClusterMembership treats the target system like a standalone machine even if it’s in a cluster. CSV folders will be ignored.
• Credential allows you to specify a set of credentials that will be used to scan remote locations. Any SMB 3 shares will always be scanned from the perspective of the local system using the credentials of the local session.

Alternate Parameter Set

• ComputerName in this set is the same as the default.
• Path accepts a string array of paths to check. Each host in the ComputerName array will be scanned for this folder. If it’s not there, you’ll just get a warning about it, so there’s no harm in including it even for systems where you know it doesn’t exist. When you manually specify paths, only those locations are scanned by default.
• IncludeDefaultPath instructs the script to scan the host’s default paths for orphans when -Path has been specified.
• IncludeExistingVMPaths instructs the script to scan the folders of existing VMs for orphans when -Path has been specified.
• IgnoreClusterMembership works in this set the same way as in the default.
• Credential in this set is same as the default.

Sample Output

The output is essentially that of Get-ChildItem. Take a look at the PSComputerName column. That will tell you which computer the file was found on. If it reports “localhost”, that means the containing folder is on a share. All others will be local or on a CSV on the indicated computer.

Script Listing

Copy and paste the included script into a file. It’s written to expect Get-OrphanedVMFiles.ps1, but you’re welcome to use anything you like. Don’t forget that copying and pasting from this site includes a tag line at the very end that you’ll need to remove.

I did not write the script to be dot-sourced. If you want to do that, encase the contents as shown:

#requires -Version 3
function Get-VMOrphanedFiles
{
	<# 	comment-based help 	#>
	[CmdletBinding(DefaultParameterSetName='UnspecifiedPath')]
	param (
		... existing parameters...
	)
	BEGIN {
		... existing BEGIN script...
	}
	PROCESS
	{
		...
		existing PROCESS script
		...
	}
	END {}
}

And here’s the script:

<#
.SYNOPSIS
	Find virtual machine files that are no longer registered to a Hyper-V host or a virtual machine.

.DESCRIPTION
	Some operations may leave the XML definition file for a virtual machine orphaned, along with other files associated with a virtual machine.
	This script detects and returns those orphaned files.

	Use caution when interpreting results from a shared location. Files owned by a Hyper-V host that was not specified will be returned as a false positive.
	Use the Host parameter to specify other hosts to include in the same scan.

.PARAMETER Path
	A array string that contains one or more source paths to search. Subfolders will automatically be searched.
	If not specified, the behavior is the same as if the IncludeDefaultPath and IncludeExistingVMPaths parameters were specified.

.PARAMETER ComputerName
	A string array that contains the name(s) of host(s) to scan. It can also contain cluster name(s).
	If not specified, the local host will be used.

.PARAMETER IncludeDefaultPath
	If the Path parameter is specified, use this parameter to indicate that the Hyper-V host's default path should also be scanned.

.PARAMETER IncludeExistingVMPaths
	If the Path parameter is specified, use this parameter to indicate that the paths of existing VMs should also be scanned.

.PARAMETER ExcludeDefaultPath
	If the Path parameter is not specified, use this parameter to prevent the host's default VM path from being scanned.

.PARAMETER ExcludeExistingVMPaths
	If the Path parameter is not specified, use this parameter to prevent the paths of existing VMs from being scanned.

.PARAMETER IgnoreClusterMembership
	Ordinarily, the script will determine if a computer is part of a cluster and scan the VMs of all nodes as a fail-safe.
	If this switch is set, only the specified system(s) will be scanned. Any paths involving ClusterStorage will be skipped.

.PARAMETER Credential
	The credential to use to connect to and scan remote hosts.
	Has no effect on SMB 3 storage locations. These will always be scanned as the locally logged-on account.

.OUTPUTS
	An array of deserialized FileInfo objects or $null if no items are found. GetType() shows the generic Object type.

.NOTES
	 Author: Eric Siron
	 Copyright: (C) 2014 Altaro Software
	 Version 1.1
	 Authored Date: October 25, 2014

	 1.2 April 11, 2016
	 ------------------------------
	 * Increased output verbosity (when -Verbose parameter is specified)
	 * Minor performance enhancements

	 1.1 December 13th, 2015
	 ------------------------------
	 * Changed suggested script name to Get-VMOrphanedFiles from Get-OrphanedVMFiles; makes more consistent with other VM scripts
	 * Replaced all instances of -notin with -notcontains to improve compatibility with other PowerShell hosts
	 * Any detected CSV will be scanned even if no host returns it as a search path (unless -SkipCSVs is specified)
	 * Added duplicate sub-folder check to SMB paths (was already functional for all other path types)
	 * Numerous refactorings for readability and a tiny bit of performance

.LINK
	 
Free Script: Find Orphaned Hyper-V VM Files


.EXAMPLE
	C:PS> .Get-VMOrphanedFiles

	Description
	-----------
	Retrieves orphaned VM files in this host's default VM path and those of current VMs.

.EXAMPLE
	C:PS> .Get-VMOrphanedFiles -Path D:

	Description
	-----------
	Retrieves orphaned VMs on this host contained anywhere on the D: drive.

.EXAMPLE
	C:PS> .Get-VMOrphanedFiles -ExcludeExistingVMPaths

	Description
	-----------
	Retrieves orphaned VM files in this host's default VM path, ignoring any paths of VMs that are outside the default.

C:PS> .Get-VMOrphanedFiles -ExcludeDefaultPath

	Description
	-----------
	Retrieves orphaned VM files in the paths of existing VMs except those contained in the host's default path.

C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path \smb3sharevms

	Description
	-----------
	Checks for VM files on the \smb3sharevms that are not connected to any VMs registered to svhv1 or svhv2.

C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path C:

	Description
	-----------
	Checks for VM files on the local C: drives of svhv1 and svhv2.

C:PS> Get-VMHost server1, server2, server3 | .Get-VMOrphanedFiles

	Description
	-----------
	Retrieves orphaned VM files in the default and current VM paths for hosts named server1, server2, and server3.

C:PS> .Get-VMOrphanedFiles -ComputerName svhv1 -Path C: -IgnoreClusterMembership

	Description
	-----------
	Retrieves orphaned VM files on the C: drive of SVHV1, skipping the ClusterStorage folder and not scanning any other hosts in the cluster.

C:PS> .Get-VMOrphanedFiles -ComputerName svhv1, svhv2 -Path -Credential (Get-Credential)

	Description
	-----------
	Checks for orphaned VM files on svhv1's and svhv2's default paths using the credentials that you specify. Files on SMB 3 storage will be scanned using the credentials of the local session.

#>

#requires -Version 3

[CmdletBinding(DefaultParameterSetName='UnspecifiedPath')]
param(
	[Alias('Host', 'HostName', 'VMHosts', 'Hosts', 'VMHost')]
	[Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
	[Object[]]$ComputerName=@(,$env:COMPUTERNAME),

	[Alias("VirtualMachinePath")]
	[Parameter(ValueFromPipeline=$true, ValueFromPipelinebyPropertyName=$true,ParameterSetName='SpecifiedPath')]
	[String[]]$Path=@(),

	[Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='SpecifiedPath')]
	[Switch]$IncludeDefaultPath,

	[Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='SpecifiedPath')]
	[Switch]$IncludeExistingVMPaths,

	[Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='UnspecifiedPath')]
	[Switch]$ExcludeDefaultPath,

	[Parameter(ValueFromPipelineByPropertyName=$true,ParameterSetName='UnspecifiedPath')]
	[Switch]$ExcludeExistingVMPaths,

	[Parameter(ValueFromPipelineByPropertyName=$true)]
	[Switch]$IgnoreClusterMembership,

	[Parameter(ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)]
	[System.Management.Automation.PSCredential]$Credential
)

BEGIN
{
	######################### Script block definitions ###############################
	$VMFilePathsScriptBlock = {
		param(
			[Parameter(Position=0)][Boolean]$ReturnDefaultPaths,
			[Parameter(Position=1)][Boolean]$ReturnVMPaths,
			[Parameter(Position=2)][System.Management.Automation.ActionPreference]$RemoteVerbosePreference = [System.Management.Automation.ActionPreference]::SilentlyContinue
		)
		function Parse-LocalOrSharedVMFilePath
		{
			param(
				[Parameter()][String]$VMHost = '',
				[Parameter()][String]$ItemType,		# 'path' for a file-system path, 'shared' for a UNC, 'metafile' for a non-disk VM file, 'disk' for a VM disk file
				[Parameter()][String]$PathOrFile,	# this is the item that will be operated on
				[Parameter()][String]$VMNameToRemove = '',	# if provided, it will be removed from the end of an item (usually to find the parent)
				[Parameter()][String]$VMId = $null
			)

			if($ItemType -eq 'converttopath')
			{
				$PathOrFile = $PathOrFile -replace '(\)[^\]*\?$'	# remove file name
				$ItemType = 'path'
			}
			if($ItemType -ne 'path')
			{
				$PathOrFile = $PathOrFile -replace '\$'	# no trailing slashes on files
			}
			if($PathOrFile -match '^\\[^?|.]')	# item is on a share
			{
				$HostPrefix = ''	# Hyper-V doesn't support SMB3 loopback, so no VMHost owns the supplied file or path
			}
			else
			{
				$PathOrFile = $PathOrFile -replace '^\\?', '\.'	# raw volume identifiers might come in with a ? but must go out with a .
				$HostPrefix = $VMHost
			}
			if(-not [String]::IsNullOrEmpty($VMNameToRemove))
			{
				$PathOrFile = $PathOrFile -replace "$VMNameToRemove\?$"	# lop off any remote path
			}
			[String]::Join(';', ($HostPrefix, $ItemType, $PathOrFile))
		}

		function Get-DifferencingChain
		{
			param(
				[Parameter()][String]$VHDPath
			)
			if($VHDPath -notmatch '^\\[^?|.]')	# the calling host will have to deal with differencing disks on shares
			{
				$VHDPath = $VHDPath -replace '^\\?', '\.'	# Get-VHD can only operate on raw volume identifiers with a . and these files haven't yet gone through the sanitizer
				Write-Verbose -Message ('Checking for parent disks of ' + $VHDPath)
				$VHD = Get-VHD -Path $VHDPath
				if($VHD.ParentPath)
				{
					Write-Verbose -Message ('Parent found, traversing chain...')
					$VHD.ParentPath
					Get-DifferencingChain $VHD.ParentPath
				}
			}
		}

		$VerbosePreference = $RemoteVerbosePreference
		$FileList = @() # this is what is returned to the calling system
		$MetaFileList = @()
		$DiskFileList = @()

		if(-not (Get-Module -Name Hyper-V -ListAvailable))
		{
			throw((Get-WmiObject -Class Win32_ComputerSystem).Name + ' does not have the Hyper-V PowerShell module installed')
		}

		Write-Verbose -Message 'Retrieving Hyper-V host information...'
		$VMHostData = Get-VMHost
		$VMHostName = $VMHostData.Name
		if($VMHostData.FullyQualifiedDomainName.Contains('.'))
		{
			$VMHostName += '.' + $VMHostData.FullyQualifiedDomainName
		}

		$VMHostName = $VMHostName.ToLower()
		Write-Verbose -Message ('Host name: ' + $VMHostName)

		$HostHVRegistrationPath = (Resolve-Path "$($env:ProgramData)MicrosoftWindowsHyper-V").Path
		Write-Verbose -Message ('Virtual machine registration path: ' + $HostHVRegistrationPath)
		
		Write-Verbose -Message ('Default virtual machine path: ' + $VMHostData.VirtualMachinePath)
		if($VMHostData.VirtualMachinePath -match '^\\[^?|.]')
		{
			$ThisHostVMPathShared = $true
			$ThisHostVMPathType = 'shared'
			Write-Verbose -Message 'The default virtual machine path is on an SMB 3 share'
		}
		else
		{
			$ThisHostVMPathShared = $false
			$ThisHostVMPathType = 'path'
			Write-Verbose -Message 'The default virtual machine path is on locally-addressed storage'
		}

		Write-Verbose -Message ('Default virtual hard disk path: ' + $VMHostData.VirtualHardDiskPath)
		if($VMHostData.VirtualHardDiskPath -match '^\\[^?|.]')
		{
			$ThisHostVMHDShared = $true
			$ThisHostVMHDType = 'shared'
			Write-Verbose -Message 'The default virtual hard disk path is on an SMB 3 share'
		}
		else
		{
			$ThisHostVMHDShared = $false
			$ThisHostVMHDType = 'path'
			Write-Verbose -Message 'The default virtual hard disk path is on locally-addressed storage'
		}
		if($ReturnDefaultPaths)
		{
			$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType $ThisHostVMPathType -PathOrFile $VMHostData.VirtualMachinePath
			Write-Verbose -Message ($VMHostData.VirtualMachinePath + ' added to scan paths')
			$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType $ThisHostVMHDType -PathOrFile $VMHostData.VirtualHardDiskPath
			Write-Verbose -Message ($VMHostData.VirtualHardDiskPath + ' added to scan paths')
			$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $HostHVRegistrationPath
			Write-Verbose -Message ($HostHVRegistrationPath + ' added to scan paths')
		}
		if(Test-Path -Path ($env:SystemDrive + 'ClusterStorage'))
		{
			Write-Verbose -Message 'Enumerating cluster shared volumes'
			foreach ($CSVPath in Get-ChildItem -Path ($env:SystemDrive + 'ClusterStorage'))
			{
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $CSVPath.FullName
				Write-Verbose -Message ($CSVPath.FullName + ' added to scan paths')
			}
		}
		foreach ($VM in Hyper-VGet-VM)
		{
			$ThisVMId = $VM.VMId
			$ThisVMPrimaryPath = $VM.Path
			if($ThisVMPrimaryPath -match '^\\[^?|.]')
			{
				$ThisVMPrimaryPathShared = $true
				$ThisVMPrimaryPathType = 'shared'
				Write-Verbose -Message ('Primary path for "{0}" is on SMB share: "{1}"' -f $VM.Name, $ThisVMPrimaryPath)
			}
			else
			{
				$ThisVMPrimaryPathShared = $false
				$ThisVMPrimaryPathType = 'path'
				Write-Verbose -Message ('Primary path for "{0}" is in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMPrimaryPath)
			}
			$ThisVMConfigurationPath = $VM.ConfigurationLocation
			if($ThisVMConfigurationPath -match '^\\[^?|.]')
			{
				$ThisVMConfigurationPathShared = $true
				$ThisVMConfigurationPathType = 'shared'
				Write-Verbose -Message ('Configuration files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMConfigurationPath)
			}
			else
			{
				$ThisVMConfigurationPathShared = $false
				$ThisVMConfigurationPathType = 'path'
				Write-Verbose -Message ('Configuration files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMConfigurationPath)
			}
			$ThisVMSnapshotPath = $VM.SnapshotFileLocation
			if($ThisVMSnapshotPath -match '^\\[^?|.]')
			{
				$ThisVMSnapshotPathShared = $true
				$ThisVMSnapshotPathType = 'shared'
				Write-Verbose -Message ('Checkpoint files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMSnapshotPath)
			}
			else
			{
				$ThisVMSnapshotPathShared = $false
				$ThisVMSnapshotPathType = 'path'
				Write-Verbose -Message ('Checkpoint files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMSnapshotPath)
			}
			$ThisVMSLPPath = $VM.SmartPagingFilePath
			if($ThisVMSLPPath -match '^\\[^?|.]')
			{
				$ThisVMSLPPathShared = $true
				$ThisVMSLPPathType = 'shared'
				Write-Verbose -Message ('Smart paging files for "{0}" are on SMB share: "{1}"' -f $VM.Name, $ThisVMSLPPath)
			}
			else
			{
				$ThisVMSLPPathShared = $false
				$ThisVMSLPPathType = 'path'
				Write-Verbose -Message ('Smart paging files for "{0}" are in locally-addressed space: "{1}"' -f $VM.Name, $ThisVMSLPPath)
			}
			# Get configuration files
			Write-Verbose -Message ('Adding configuration files for "' + $VM.Name + '" to scan list')
			$MetaFileList += (Get-ChildItem -File -Path $HostHVRegistrationPath -Recurse -Filter "$ThisVMId.xml").FullName
			if($ThisVMConfigurationPathShared)
			{
				$ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMConfigurationPath
				$FileList += [String]::Join(',', ($ThisItem, $ThisVMId, $VM.Name, 'configuration'))
			}
			else
			{
				$MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.xml").FullName
				$MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.bin").FullName
				$MetaFileList += (Get-ChildItem -File -Path $ThisVMConfigurationPath -Recurse -Filter "$ThisVMId.vsv").FullName
			}
			# Get snapshot files
			Write-Verbose -Message ('Adding checkpoint files for "' + $VM.Name + '" to scan list')
			if($ThisVMSnapshotPathShared)
			{
				$ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMSnapshotPath
				$FileList += [String]::Join(",", ($ThisItem, $ThisVMId, $VM.Name, 'snapshotpath'))
			}
			else
			{
				$SnapshotRoot = (Get-ChildItem -Directory -Path $ThisVMSnapshotPath -Filter 'Snapshots').FullName
			}
			Get-VMSnapshot -VM $VM | foreach {
				Write-Verbose -Message ('Adding checkpoint files for "' + $VM.Name + '" with ID: "' + $_.Id + '" to scan list')
				$MetaFileList += (Get-ChildItem -File -Path $HostHVRegistrationPath -Recurse -Filter "$($_.Id).xml").FullName
				if($ThisVMSnapshotPathShared)
				{
					$SharedFileList += [String]::Join(",", ($ThisVMSnapshotPath, $_.Id, 'snapshot'))
				}
				else
				{
					$MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).xml").FullName
					$MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).vsv").FullName
					$MetaFileList += (Get-ChildItem -File -Path $SnapshotRoot -Recurse -Filter "$($_.Id).bin").FullName
				}
				Get-VMHardDiskDrive -VMSnapshot $_ | foreach {
					$DiskFileList += $_.Path
					if($ReturnVMPaths)
					{
						$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($_.Path)
					}
				}
				if($VM.Generation -lt 2)
				{
					Get-VMFloppyDiskDrive -VMSnapshot $_ | foreach {
						if($_.Path)
						{
							$DiskFileList += $_.Path
							if($ReturnVMPaths)
							{
								$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($_.Path)
							}
						}
					}
				}
			}
			# Get Smart Paging files
			Write-Verbose -Message ('Adding smart paging files for "' + $VM.Name + '" to scan list')
			if($VM.SmartPagingFileInUse)
			{
				if($ThisVMSLPPathShared)
				{
					$ThisItem = Parse-LocalOrSharedVMFilePath -ItemType 'shared' -PathOrFile $ThisVMSLPPath
					$FileList += [String]::Join(',', ($ThisItem, $ThisVMId, $VM.Name, 'slp'))
				}
				else
				{
					$MetaFileList += (Get-ChildItem -File -Path $ThisVMSLPPath -Recurse -Filter "$($_.Id).*.slp").FullName
				}
			}

			# Get virtual hard/floppy disks
			Write-Verbose -Message ('Adding virtual disk files for "' + $VM.Name + '" to scan list')
			Get-VMHardDiskDrive -VM $VM | foreach {
				$ThisVMDiskList = @()
				$ThisVMDiskList += $_.Path
				$ThisVMDiskList += Get-DifferencingChain $_.Path
				if($ReturnVMPaths)
				{
					foreach($VMDisk in $ThisVMDiskList)
					{
						$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'converttopath' -PathOrFile ($VMDisk)
					}
				}
				$DiskFileList += $ThisVMDiskList
			}

			if($VM.Generation -lt 2)
			{
				$DiskFileList += (Get-VMFloppyDiskDrive -VM $VM).Path
			}
		}
		$MetaFileList | foreach {
			if(-not [String]::IsNullOrEmpty($_))
			{
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'metafile' -PathOrFile $_
			}
		}
		$DiskFileList | foreach {
			if(-not [String]::IsNullOrEmpty($_))
			{
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'disk' -PathOrFile $_
			}
			if($ReturnVMPaths)
			{
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMPrimaryPath -VMNameToRemove $_.Name
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMConfigurationPath -VMNameToRemove $_.Name
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMSnapshotPath -VMNameToRemove $_.Name
				$FileList += Parse-LocalOrSharedVMFilePath -VMHost $VMHostName -ItemType 'path' -PathOrFile $ThisVMSLPPath -VMNameToRemove $_.Name
			}
		}
		$FileList | select -Unique
	}

	$SearchScriptBlock = {
		param
		(
			[Parameter(Position=0)][String[]]$SearchPaths,
			[Parameter(Position=1)][String[]]$FileExclusions,
			[Parameter(Position=2)][String[]]$DiskExclusions,
			[Parameter(Position=3)][Boolean]$SkipCSVs
		)
		function Escape-Path {
			param(
				[Parameter()][String]$Path
			)
			try {
				$ReturnPath = (Resolve-Path -Path $Path -ErrorAction Stop).Path
				$ReturnPath -replace "\", "\"	# This is not a typo. This turns single backslashes into double backslashes. I promise.
			}
			catch
			{
				# just means the path wasn't there
			}
		}
		$LocalClusterStorage = (Escape-Path -Path "$($env:SystemDrive)ClusterStorage")
		$DirectoryExclusions = @(
			(Escape-Path -Path "$($env:SystemRoot)Vss"),	# vss writers are also registered as <guid>.xml
			(Escape-Path -Path "$($env:SystemRoot)WinSxs"),	# many things in here will trigger a response
			(Escape-Path -Path "$($env:ProgramData)MicrosoftWindowsHyper-VResource Types")	# HV resource types are also registered as <guid>.xml
		)
		if($SkipCSVs)
		{
			$DirectoryExclusions += $LocalClusterStorage
		}
		foreach($SearchPath in $SearchPaths)
		{
			try	# because Test-Path doesn't work on raw volume identifiers, that's why
			{
				Get-ChildItem -Path $SearchPath -ErrorAction Stop | Out-Null
				$PathFound = $true
			}
			catch
			{
				$PathFound = $false
			}
			if($PathFound)
			{
				$CompareGUID = New-Object System.Guid
				Get-ChildItem -File -Path $SearchPath -Recurse |
					where {
						# first, parse the extension for virtual hard/floppy disk files as that is the fastest of possible operations
						if($_.Extension -match "v(h|f)d")
						{
							if($SkipCSVs -and $_.DirectoryName -match $LocalClusterStorage)
							{
								$false
							}
							elseif($DiskExclusions -notcontains $_.FullName.ToLower())
							{
								$true
							}
						}
						elseif($_.Extension -match "xml|bin|vsv")
						{
							$InExcludedDirectory = $false
							$DirectoryName = $_.DirectoryName
							$DirectoryExclusions |
							foreach {
								if($DirectoryName -match $_)
								{
									$InExcludedDirectory = $true
								}
							}
							if(-not $InExcludedDirectory)
							{
								#VM files of this type will all be formatted as a GUID
								if([System.Guid]::TryParse($_.BaseName, [ref]$CompareGUID))
								{
									if($FileExclusions -notcontains $_.FullName.ToLower())
									{
										$true
									}
								}
							}
						}
					}
			}
		}
	}

	######################### Function definitions ###############################
	function Parse-LocalOrSharedItem
	{
		<#
			.DESCRIPTION
			Determines if a path is on a local system or is shared. If local, attaches it to the submitted host name for later processing.
			Also cleans up path entries for use with later functions and cmdlets.
		#>
		param(
			[Parameter()][String]$CurrentPath,
			[Parameter()][String]$CurrentHost = ""
		)
		$CurrentPath = $CurrentPath -replace "`"|'"	# remove quotes
		$CurrentPath = $CurrentPath -replace "^\\?", "\."
		if($CurrentPath -match "^\\[^.]" -or [String]::IsNullOrEmpty($CurrentHost))
		{
			$($CurrentPath.ToLower())
		}
		else
		{
			([String]::Join(",", ($CurrentPath, $CurrentHost))).ToLower()
		}
	}

	function Dedupe-CSV
	<#
		Resets all items that target *clusterstorage* so that the same location isn't scanned from multiple nodes or false positives returned.
		Also, if the IgnoreClusterMembership flag is set, these items are simply removed so that they won't be scanned at all.
	#>
	{
		param(
			[Parameter()][String[]]$ClusterList,
			[Parameter()][String[]]$ArrayWithCSV	# this script was designed so that computer names will always appear in element[1]
		)
		$ItemsToRemove = @()
		$ReplacementItems = @()
		foreach($ClusterItem in $ClusterList)
		{
			$PrimaryNode = $ClusterItem.Split(";")[0]
			$NodeList = $ClusterItem.Split(";")[1]
			foreach($ItemWithCSV in $ArrayWithCSV)
			{
				if($ItemWithCSV -match ":\clusterstorage")
				{
					$PathOrItem = $ItemWithCSV.Split(",")[0]
					$OriginalNode = $ItemWithCSV.Split(",")[1]
					if($PrimaryNode -ne $OriginalNode)
					{
						$ItemsToRemove += $ItemWithCSV
						if(-not $IgnoreClusterMembership)
						{
							$ReplacementItems += [String]::Join(",", ($PathOrItem, $PrimaryNode))
						}
					}
				}
			}
		}
		if($ItemsToRemove.Count -gt 0 -and $ReplacementItems.Count -gt 0)
		{
			$ArrayWithCSV = $ArrayWithCSV | where { $ItemsToRemove -notcontains $_ }
			$ArrayWithCSV + $ReplacementItems
		}
		else
		{
			$ArrayWithCSV
		}
	}

	function Remove-SubPaths
	{
		<#
			.DESCRIPTION
			Given an array of paths, finds items that are subpaths of another and removes them
		#>
		param(
			[Parameter()]$PathArray
		)
		$PathsToRemove = @()
		foreach($PathOuter in $PathArray)
		{
			if($IgnoreClusterMembership -and $PathOuter -match "(:|\\[.|?]\Volume{.*})\ClusterStorage")	# function re-usability warning on $IgnoreClusterMembership
			{
				$PathsToRemove += $PathOuter
			}
			else
			{
				foreach($PathInner in $PathArray)
				{
					if($PathOuter -ne $PathInner)
					{
						$Path1 = $PathOuter.Split(",")
						$Path2 = $PathInner.Split(",")
						$CanProcess = $true
						if($Path1[1].Length -gt 0 -and $Path2[1].Length -gt 0)
						{
							if($Path1[1] -ne $Path2[1])
							{
								$CanProcess = $false
							}
						}
						if($CanProcess)
						{
							if($Path1[0].Contains($Path2[0]))
							{
								$PathsToRemove += $PathOuter
							}
						}
					}
				}
			}
		}
		$PathArray | where { $PathsToRemove -notcontains $_ } | select -Unique
	}

	function Get-RemoteData
	{
		<#
			.DESCRIPTION
			A generic function that runs the indicated scriptblock in parallel against the indicated group of hosts and returns the results as an array.
		#>
		param(
			[Parameter()][String[]]$VMHosts,
			[Parameter()][ScriptBlock]$ScriptBlock,
			[Parameter()][String]$InvokeErrorTemplate,
			[Parameter()][String]$ResultsErrorTemplate,
			[Parameter()][Object[]]$ArgumentList = $null,
			[Parameter()][System.Management.Automation.PSCredential]$Credential = $null,
			[Parameter()][String]$VerboseAction=''
		)
		$SessionList = @()
		$JobList = @()
		$ResultsArray = @()
		$ArgumentList += $VerbosePreference

		foreach($VMHost in $VMHosts)
		{
			try
			{
				$SessionParameters = @{'ComputerName'=$VMHost;'ErrorAction'='Stop' }
				if($Credential)
				{
					$SessionParameters.Add('Credential', $Credential)
				}
				Write-Verbose -Message ('Establishing a PowerShell session on ' + $VMHost)
				$Session = New-PSSession @SessionParameters
				$JobList += Invoke-Command -Session $Session -ScriptBlock $ScriptBlock -ErrorAction Stop -AsJob -ArgumentList $ArgumentList
				$SessionList += $Session
			}
			catch [Exception]
			{
				Write-Error -Message ($InvokeErrorTemplate -f $VMHost, $_)
			}
		}
		if($JobList.Count)
		{
			Wait-Job -Job $JobList -ErrorAction Stop | Out-Null
		}
		foreach($Job in $JobList)
		{
			try
			{
				$ResultsArray += Receive-Job -Job $Job -ErrorAction Stop
			}
			catch
			{
				Write-Error -Message ($ResultsErrorTemplate -f $Job.Location, $_)
				$VMHosts = $VMHosts | where { $_ -ne $VMHost }
			}
		}
		$SessionList | Remove-PSSession
		$JobList | Remove-Job
		$ResultsArray
	}

	function Get-VHDDifferencingParent
	{
		param(
			[Parameter(Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)][String]$Path
		)

		$AbsolutePath = ""
		$IdentifierSize = 8
		$IdentifierBytes = New-Object Byte[] $IdentifierSize

		try
		{
			try
			{
				$VHDStream = New-Object System.IO.FileStream($Path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite) -ErrorAction Stop
			}
			catch
			{
				throw ("Unable to open differencing disk {0} to determine its parent: {1}" -f $Path, $_)
			}

			try
			{
				$BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize)
			}
			catch
			{
				throw ("Unable to read the VHD type identifier for {0}: {1}" -f $Path, $_)
			}

					if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "vhdxfile")
			{
				$1stRegionOffset = 196608; $1stRegionEntryCount = 0; $2ndRegionOffset = 262144; $2ndRegionEntryCount = 0
				$SignatureSize = 4; $EntryCountSize = 8; $GUIDSize = 16; $EntryOffsetSize = 8; $EntryLengthSize = 4
				$ShortEntrySize = 2; $MetadataOffsetSize = 4; $KeyValueCountSize = 2; $LocatorEntrySize = 12
				$SignatureBytes = New-Object Byte[] $SignatureSize; $EntryCountBytes = New-Object Byte[] $EntryCountSize
				$GUIDBytes = New-Object Byte[] $GUIDSize; $EntryOffset = New-Object Byte[] $EntryOffsetSize
				$ShortEntryBytes = New-Object Byte[] $ShortEntrySize; $MetadataOffsetBytes = New-Object Byte[] $MetadataOffsetSize
				$KeyValueCountBytes = New-Object Byte[] $KeyValueCountSize; $LocatorEntryBytes = New-Object Byte[] $LocatorEntrySize
				$LocatorEntries = @()

				($1stRegionOffset, $2ndRegionOffset) | foreach {
					$VHDStream.Position = $_
					try
					{
						$BytesRead = $VHDStream.Read($SignatureBytes, 0, $SignatureSize)
					}
					catch
					{
						throw ("Unable to read signature from header region of {0}: {1}" -f $Path, $_)
					}
					if([System.Text.Encoding]::ASCII.GetString($SignatureBytes) -eq "regi")
					{
						$VHDStream.Position += 4	# jump over the checksum
						try
						{
							$BytesRead = $VHDStream.Read($EntryCountBytes, 0, $EntryCountSize)
						}
						catch
						{
							throw ("Unable to determine number of header entries in {0}: {1}" -f $Path, $_)
						}
						$RegionEntryCount = [System.BitConverter]::ToInt32($EntryCountBytes, 0)
						if($_ = $1stRegionOffset)
						{
							$1stRegionEntryCount = $RegionEntryCount
						}
						else
						{
							$2ndRegionEntryCount = $RegionEntryCount
						}
					}
				}
				if($1stRegionEntryCount -ge $2ndRegionEntryCount)
				{
					$EntryCount = $1stRegionEntryCount
					$StartingEntryOffset = $1stRegionOffset + 16
				}
				else
				{
					$EntryCount = $2ndRegionEntryCount
					$StartingEntryOffset = $2ndRegionOffset + 16
				}

				1..$EntryCount | foreach {
					$VHDStream.Position = $StartingEntryOffset + (32 * ($_ - 1))	# an entry is 32 bytes long
					try
					{
						$BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize)
					}
					catch
					{
						throw ("Unable to retrieve the GUID of a header entry in {0}, {1}" -f $Path, $_)
					}
					if([System.BitConverter]::ToString($GUIDBytes) -eq "06-A2-7C-8B-90-47-9A-4B-B8-FE-57-5F-05-0F-88-6E")	# this is the GUID of a metadata region
					{
						try
						{
							$BytesRead = $VHDStream.Read($EntryOffset, 0, $EntryOffsetSize)
						}
						catch
						{
							throw("Unable to determine the location of a metadata region in {0}: {1}" -f $Path, $_)
						}
						$MetadataStart = $VHDStream.Position = [System.BitConverter]::ToInt64($EntryOffset, 0)

						try
						{
							$BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize)
						}
						catch
						{
							throw("Unable to parse the identifier of an expected metadata region in {0}: {1}"-f $Path, $_)
						}
						if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "metadata")
						{
							$VHDStream.Position += 2	# jump over reserved field
							try
							{
								$BytesRead = $VHDStream.Read($ShortEntryBytes, 0, $ShortEntrySize)
							}
							catch
							{
								throw("Unable to retrieve the number of header short entries in {0}: {1}" -f $Path, $_)
							}
							$VHDStream.Position += 20	# jump over the rest of the header
							1..([System.BitConverter]::ToUInt16($ShortEntryBytes, 0)) | foreach {
								try
								{
									$BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize)
								}
								catch
								{
									throw ("Unable to retrieve the GUID of a short entry in {0}: {1}" -f $Path, $_)
								}
								$SavedStreamPosition = $VHDStream.Position
								switch([System.BitConverter]::ToString($GUIDBytes))
								{	## We're only watching for a single item so an "if" could do this, but switch is future-proofing.
									## Should be able to query 37-67-A1-CA-36-FA-43-4D-B3-B6-33-F0-AA-44-E7-6B for a "HasParent" value, but either the documentation is wrong or the implementation is broken as this field holds the same value for all disk types
									"2D-5F-D3-A8-0B-B3-4D-45-AB-F7-D3-D8-48-34-AB-0C" {	# Parent Locator
										try
										{
											$BytesRead = $VHDStream.Read($MetadataOffsetBytes, 0, $MetadataOffsetSize)
										}
										catch
										{
											throw ("Unable to read the location of a metadata entry in {0}: {1}" -f $Path, $_)
										}

										if($BytesRead)
										{
											$ParentLocatorOffset = $MetadataStart + [System.BitConverter]::ToInt32($MetadataOffsetBytes, 0)
											$VHDStream.Position = $ParentLocatorOffset + 18 # jump over the GUID and reserved fields

											try
											{
												$BytesRead = $VHDStream.Read($KeyValueCountBytes, 0, $KeyValueCountSize)
											}
											catch
											{
												throw("Unable to read the number of key/value metadata sets in {0}: {1}" -f $Path, $_)
											}
											if($BytesRead)
											{
												1..[System.BitConverter]::ToUInt16($KeyValueCountBytes, 0) | foreach {
													try
													{
														$BytesRead = $VHDStream.Read($LocatorEntryBytes, 0, $LocatorEntrySize)
													}
													catch
													{
														throw ("Unable to retrieve a key/value metadata set from {0}: {1}" -f $Path, $_)
													}
													if($BytesRead)
													{
														$KeyOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 0)
														$ValueOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 4)
														$KeyLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 8)
														$ValueLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 10)
														$LocatorEntries += [String]::Join(",", ($KeyOffset, $ValueOffset, $KeyLength, $ValueLength))
													}
												}
												foreach($Locator in $LocatorEntries)
												{
													$KeyValueSet = $Locator.Split(",")
													$KeyPosition = $ParentLocatorOffset + $KeyValueSet[0]
													$ValuePosition = $ParentLocatorOffset + $KeyValueSet[1]
													$KeyBytes = New-Object Byte[] $KeyValueSet[2]
													$ValueBytes = New-Object Byte[] $KeyValueSet[3]
													$VHDStream.Position = $KeyPosition

													try
													{
														# NOTE: we don't actually do anything with the key, technically could move the pointer past it to the value
														$BytesRead = $VHDStream.Read($KeyBytes, 0, $KeyBytes.Length)
													}
													catch
													{
														throw ("Unable to retrieve the parent path key in the key/value set of {0}: {1}")
													}
													if($BytesRead)
													{
														if([System.Text.Encoding]::Unicode.GetString($KeyBytes) -eq "absolute_win32_path")
														{
															try
															{
																$BytesRead = $VHDStream.Read($ValueBytes, 0, $ValueBytes.Length)
															}
															catch
															{
																throw ("Unable to retrieve the parent path value in the key/value set of {0}: {1}")
															}
															if($BytesRead)
															{
																$AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ValueBytes)
																break
															}
														}
													}
												}
											}
										}
									}
								}
								# move to the start of the next entry
								$VHDStream.Position = $SavedStreamPosition + 16
							}
						}
					}
				}
			}
			elseif([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "conectix") # this is a VHD file
			{
				$TypeSize = 4; $ChunkSize = 2
				$TypeBytes = New-Object Byte[] $TypeSize -ErrorAction Stop; $ChunkBytes = New-Object Byte[] $ChunkSize -ErrorAction Stop
				$ReverseParentBytes = [Byte[]]@()
				$VHDStream.Position = 60	# this is where the disk type is stored
				try
				{
					$BytesRead = $VHDStream.Read($TypeBytes, 0, $TypeSize)
				}
				catch
				{
					throw ("Unable to determine the disk type of {0}: {1}" -f $Path, $_)
				}
				if($BytesRead)
				{
					[Array]::Reverse($TypeBytes)	# surprise byte reversal!
					if([System.BitConverter]::ToUInt32($TypeBytes, 0) -eq 4)	# is the differencing type
					{
						$VHDStream.Position = 576	# this is where the name of the parent is stored, if any
						1..256 | foreach {	# there are 512 bytes in the name, but they're also reversed. this is much more miserable to fix
							try
							{
								$BytesRead = $VHDStream.Read($ChunkBytes, 0, $ChunkSize)
							}
							catch
							{
								throw ("Unable to read the parent of {0}: {1}" -f $Path, $_)
							}
							if($BytesRead)
							{
								[Array]::Reverse($ChunkBytes)
								$ReverseParentBytes += $ChunkBytes
							}
						}
						$AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ReverseParentBytes) -replace "(?<=.vhd).*"	# remove leftover noise
					}
				}
			}
			else
			{
				throw ("{0} is not a valid VHD(X) file or has a damaged header" -f $Path)
			}
		}
		catch
		{	<#
				PowerShell does not implement any form of "goto" or "using", so the purpose of this outer try block is to simulate goto functionality with an ending point
				that ensures that the file is always closed, if one was opened. otherwise, PS's normal erroring is sufficient
			#>
			throw($_)
		}
		finally
		{
			if($VHDStream)
			{
				$VHDStream.Close()
			}
		}
		$AbsolutePath
	}
}

PROCESS
{
	$VMHosts = [String[]]@()	# verified list of hosts to scan; built from -ComputerName; cluster nodes will be added automatically
	$Clusters = [String[]]@()	# discovered clusters. item format: primary node; node1, node2, node3, ...
	$RemotePathsToScan = @()	# any paths to scan that are not on a share; even local paths will be scanned via remote session, includes host name
	$SharedPathsToScan = @()	# any shared paths to scan
	$RemoteMetaFileExclusions = @()	# known good xml, bin, vsv, and slp files that are not on a share, includes host name
	$RemoteDiskFileExclusions = @()	# known good vhd, vhdx, avhd, avhdx, and vfd files that are not on a share, includes host name
	$SharedMetaFileExclusions = @()	# known good xml, bin, vsv, and slp files that are on a share
	$SharedDiskFileExclusions = @()	# known good vhd, vhdx, avhd, avhdx, and vfd files that are on a share

	######################### Validate input parameters ###############################
	switch($PSCmdlet.ParameterSetName)
	{
		'SpecifiedPath' {
			$UseDefaultPath = $IncludeDefaultPath
			$UseExistingVMPaths = $IncludeExistingVMPaths
		}
		'UnspecifiedPath' {
			$UseDefaultPath = -not $ExcludeDefaultPath
			$UseExistingVMPaths = -not $ExcludeExistingVMPaths
		}
	}
	if([String]::IsNullOrEmpty($Path) -and -not $UseDefaultPath -and -not $UseExistingVMPaths)
	{
		throw('No path specified for scan')
	}

	Write-Verbose -Message "Using default path(s): $UseDefaultPath"
	Write-Verbose -Message "Using existing VM path(s): $UseExistingVMPaths"

	######################### Validate host list ###############################
	Write-Verbose "Verifying hosts"
	foreach ($VMHost in $ComputerName)
	{
		if($VMHost.GetType().ToString() -match "Microsoft.HyperV.PowerShell.VMHost")
		{
			$VMHost = $VMHost.Name
		}
		try
		{
			$GwmiComputerParameters = @{'ComputerName'=$VMHost;'Class'='Win32_ComputerSystem';'ErrorAction'='Stop' }
			if($Credential)
			{
				$GwmiComputerParameters.Add('Credential', $Credential)
			}
			$ComputerObject = Get-WmiObject @GwmiComputerParameters
		}
		catch
		{
			Write-Warning "Unable to contact $VMHost. Skipping."
			$VMHost = ""
		}
		if(-not [String]::IsNullOrEmpty($VMHost))
		{
			$ShortName = $ComputerObject.Name.ToLower()
			if($ComputerObject.Domain.Contains("."))	# this will drop the ball for single-level domains, but people with single-level domains have bigger problems than a few VM files going astray so the extra effort to determine if it's truly a domain member is probably not worth it
			{
				$VMHost = [String]::Join(".", ($ShortName, $ComputerObject.Domain))
				if(-not $IgnoreClusterMembership)
				{
					try
					{
						$GwmiNodeParameters = @{'ComputerName'=$VMHost;'Class'='MSCluster_Node';'Namespace'='rootMSCluster';'ErrorAction'='Stop' }
						if($Credential)
						{
							$GwmiNodeParameters.Add('Credential',$Credential)
						}
						$Nodes = (Get-WmiObject @GwmiNodeParameters).Name
						$GwmiClusterDomainParameters = @{'ComputerName'=$VMHost;'Class'='Win32_ComputerSystem';'Namespace'='rootCIMV2';'ErrorAction'='Stop' }
						if($Credential)
						{
							$GwmiClusterDomainParameters.Add('Credential',$Credential)
						}
						$ClusterDomain = (Get-WmiObject @GwmiClusterDomainParameters).Domain
						$Nodes = $Nodes | foreach { "$_.$ClusterDomain" }
						foreach($Node in $Nodes)
						{
							if($VMHosts -notcontains $Node)
							{
								Write-Verbose "Adding $Node to scan list"
								$VMHosts += $Node
							}
						}
						$Clusters += [String]::Join(";", ("$($Nodes[0])", ([String]::Join(",", $Nodes))))
					}
					catch
					{
						# this just means that the target system isn't a cluster node
					}
				}
			}
			else
			{
				$VMHost = $ShortName
			}
			if($VMHosts -notcontains $VMHost)
			{
				Write-Verbose -Message "Adding $VMHost to scan list"
				$VMHosts += $VMHost
			}
		}
	}

	######################### Build exclusion and scan paths lists ###############################
	$ExclusionsAndPaths = Get-RemoteData `
		-VMHosts $VMHosts `
		-ScriptBlock $VMFilePathsScriptBlock `
		-InvokeErrorTemplate "Unable to connect to {0}`r`n{1}" `
		-ResultsErrorTemplate "An error occurred while retrieving host and VM data from {0}`r`n{1}" `
		-ArgumentList @($UseDefaultPath, $UseExistingVMPaths) `
		-Credential $Credential `
		-VerboseAction 'Retrieving virtual machine files and paths'

	foreach($EPItem in $ExclusionsAndPaths)
	{
		$FullItem = $EPItem.Split(';')
		if($FullItem[1] -eq 'metafile')
		{
			$RemoteMetaFileExclusions += Parse-LocalOrSharedItem -CurrentPath $FullItem[2] -CurrentHost $FullItem[0]
		}
		elseif($FullItem[1] -eq 'disk')
		{
			$DiskFileExclusion = Parse-LocalOrSharedItem -CurrentPath $FullItem[2] -CurrentHost $FullItem[0]
			if($DiskFileExclusion.Contains(','))
			{
				$RemoteDiskFileExclusions += $DiskFileExclusion
			}
			else
			{
				$SharedDiskFileExclusions += $DiskFileExclusion
			}
		}
		elseif($FullItem[1] -eq 'path')
		{
			$ThisPath = $FullItem[2]
			if($ThisPath -match '^\\[^?|.]')
			{
				$SharedPathsToScan += Parse-LocalOrSharedItem -CurrentPath $ThisPath
			}
			else
			{
				$RemotePathsToScan += Parse-LocalOrSharedItem -CurrentPath $ThisPath -CurrentHost $FullItem[0]
			}
		}
		else # 'shared'
		{
			$SharedPathItem = $FullItem[2].Split(',')
			$SharedPath = $SharedPathItem[0]
			$VMId = $SharedPathItem[1]
			$VMName = $SharedPathItem[2]
			$SharedItemType = $SharedPathItem[3]
			switch($SharedItemType)
			{
				{ 'configuration' -or 'snapshot' } {
					$SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.xml").FullName
					$SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.bin").FullName
					$SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.vsv").FullName
				}
				'slp' {
					$SharedMetaFileExclusions += (Get-ChildItem -File -Path $SharedPath -Recurse -Filter "$VMId.*.slp").FullName
				}
			}
		}
	}
	foreach($SharedDiskFile in $SharedDiskFileExclusions)
	{
		try
		{
			$DiskFile = (Get-Item -Path $SharedDiskFile -ErrorAction Stop).FullName
		}
		catch
		{
			Write-Error -Message "Unable to access $SharedDiskFile`r`n$_"
		}
		if(-not [String]::IsNullOrEmpty($DiskFile))
		{
			Write-Verbose -Message ("Determining the parent (if any) of {0}" -f $DiskFile)
			try
			{
				$Parent = Get-VHDDifferencingParent -Path $DiskFile -ErrorAction Stop
				while(-not [String]::IsNullOrEmpty($Parent))
				{
					$SharedDiskFileExclusions += $Parent
					Write-Verbose -Message ("Determining the parent (if any) of {0}" -f $Parent)
					$Parent = Get-VHDDifferencingParent -Path $Parent
				}
			}
			catch
			{
				Write-Error $_
			}
		}
	}

	# perform basic sanitization of user-supplied paths; no need to get crazy as PowerShell will throw its own errors on malformed paths without damaging the system
	if($Path.Count)
	{
		foreach($PathItem in $Path)
		{
			if($PathItem -notmatch '\$')
			{
				$PathItem += ''	# for some reason, script behaves erratically when root drives are supplied without trailing slashes (e.g. 'c:'); forcing a trailing slash corrects this
			}
			if($PathItem -match '^\\[^?|.]')	# matches on share paths but not raw volume identifiers
			{
				$SharedPathsToScan += Parse-LocalOrSharedItem -CurrentPath $PathItem
			}
			else
			{
				foreach($VMHost in $VMHosts)	# when user supplies a path, look for it on every host; script can handle paths that don't exist everywhere
				{
					$RemotePathsToScan += Parse-LocalOrSharedItem -CurrentPath $PathItem -CurrentHost $VMHost
				}
			}
		}
	}

	# eliminate scanning the same CSV locations from different hosts by retargeting all CSV scans to the first cluster node
	$RemotePathsToScan = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemotePathsToScan
	$RemoteMetaFileExclusions = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemoteMetaFileExclusions
	$RemoteDiskFileExclusions = Dedupe-CSV -ClusterList $Clusters -ArrayWithCSV $RemoteDiskFileExclusions

	# Paths are collected; eliminate duplicates
	$RemotePathsToScan = $RemotePathsToScan | select -Unique
	$SharedPathsToScan = Remove-SubPaths -PathArray $SharedPathsToScan
	$SharedPathsToScan = $SharedPathsToScan | select -Unique

	if($PSCmdlet.MyInvocation.BoundParameters.ContainsKey('Verbose'))
	{
		foreach($PathItem in $RemotePathsToScan)
		{
			$PathDetail = $PathItem.Split(',')
			if($PathDetail[1].Length -gt 0)
			{
				$Addition = " on $($PathDetail[1])"
			}
			else
			{
				$Addition = ''
			}
			Write-Verbose -Message "Scan list entry: $($PathDetail[0])$Addition"
		}
		foreach($PathItem in $SharedPathsToScan)
		{
			Write-Verbose -Message "Scan list entry: $PathItem"
		}
	}

	# Start scanning
	$SessionList = @()
	$JobList = @()
	foreach($VMHost in $VMHosts)
	{
		$TargetSystemPaths = @()
		$TargetSystemFileExclusions = @()
		$TargetSystemDiskExclusions = @()
		$SkipCSVs = $IgnoreClusterMembership

		if(-not $SkipCSVs)
		{
			$VMHostIsPrimary = $false
			foreach($Cluster in $Clusters)
			{
				if($VMHost -eq $Cluster.Split(";")[0])
				{
					$VMHostIsPrimary = $true
				}
			}
			$SkipCSVs = -not $VMHostIsPrimary
		}

		foreach($PathItem in $RemotePathsToScan)
		{
			$SearchPath = $PathItem.Split(",")[0]
			$SearchHost = $PathItem.Split(",")[1]
			if($VMHost -eq $SearchHost -or [String]::IsNullOrEmpty($SearchHost))
			{
				$TargetSystemPaths += $SearchPath.ToLower()
				Write-Verbose -Message ('Adding "{0}" to search paths on "{1}"' -f $SearchPath, $VMHost)
			}
		}
		foreach($ExclusionItem in $RemoteMetaFileExclusions)
		{
			$Exclusion = $ExclusionItem.Split(",")[0]
			$ExclusionHost = $ExclusionItem.Split(",")[1]
			if($VMHost -eq $ExclusionHost)
			{
				$TargetSystemFileExclusions += $Exclusion.ToLower()
				Write-Verbose -Message ('Excluding "{0} from search on "{1}"' -f $Exclusion, $VMHost)
			}
		}
		foreach($ExclusionItem in $RemoteDiskFileExclusions)
		{
			$Exclusion = $ExclusionItem.Split(",")[0]
			$ExclusionHost = $ExclusionItem.Split(",")[1]
			if($VMHost -eq $ExclusionHost)
			{
				$TargetSystemDiskExclusions += $Exclusion.ToLower()
				Write-Verbose -Message ('Excluding "{0} from search on "{1}"' -f $Exclusion, $VMHost)
			}
		}

		# eliminate sub-paths of directories already marked to be scanned
		$TargetSystemPaths = Remove-SubPaths -PathArray $TargetSystemPaths

		# knock out any duplicates generated from previous operations
		$TargetSystemPaths = $TargetSystemPaths | select -Unique
		$SessionParameters = @{'ComputerName'=$VMHost}
		if($Credential)
		{
			$SessionParameters.Add('Credential', $Credential)
		}
		Write-Verbose "Establishing a remote session on $VMHost"
		$Session = New-PSSession @SessionParameters
		Write-Verbose "Initiating orphaned file scan on $VMHost"
		$JobList += Invoke-Command -Session $Session -ScriptBlock $SearchScriptBlock -AsJob -ArgumentList $TargetSystemPaths, $TargetSystemFileExclusions, $TargetSystemDiskExclusions, $SkipCSVs
		$SessionList += $Session
	}
	foreach($PathItem in $SharedPathsToScan)
	{
		Write-Verbose -Message "Scanning $PathItem for orphaned files"
		$JobList += Start-Job -ScriptBlock $SearchScriptBlock -ArgumentList $PathItem, $SharedMetaFileExclusions, $SharedDiskFileExclusions
	}
	if($JobList.Count)
	{
		Write-Verbose -Message 'Waiting for remote scans to complete'
		Wait-Job -Job $JobList | Out-Null
		Write-Verbose -Message "Retrieving file lists"
		$FileList = Receive-Job -Job $JobList
		$JobList | Remove-Job
	}
	$SessionList | Remove-PSSession
	$FileList
}

END {}

Bonus Script

The important parts of this script are contained in the body of the main script above, but I thought its contents might be useful to anyone trying to use PowerShell or .Net to work with the metadata or contents of VHD and/or VHDX files. I needed it in the above script because I promised that you could run it from any remote system, even one without the Hyper-V PowerShell module installed. Because of that, I needed some way to check VHD files to see if they are differencing disks, and if so, to retrieve their parent disk files to exclude them as orphans. To do that with a Microsoft-developed PowerShell script, you need Get-VHD. Get-VHD doesn’t only need the PowerShell module installed, it also requires the Hyper-V role to be enabled. I didn’t think it was fair to expect you to do all that just to see if a VHD on a share is a differencing disk or not, so I built a function that only needs the default PowerShell modules.

I only needed to know enough about the file to see what its parent VHD(X)s are, but there is more than enough example here to help someone go so far as to build a complete VHD(X) parser, if desired. I/O operations have always been one of my weakest programming skills, so I pretty much abandoned any notions of designing an efficient script and went for one that more or less maximizes readability. It works more than quickly enough for my purposes, but I would highly recommend that if you intend to build this into something intended for a heavier role that you spend some time optimizing what I’m leaving you.

This script illustrates how to safely open a VHD(X) file for reading, even if it’s in use by Hyper-V. It shows how to step through the components of the file to look for the information that you need. It also includes a couple of methods for deciphering the bizarre information encoding patterns of VHD files. Look in the .NOTES section of the comment-based help for links to download the specifications for both VHD and VHDX files which can help you to design a script for whatever you’re looking for.

Note: Even though this script is always safe to run, I’ve gotten semaphore timeouts while reading very large files at the other end of an SMB share.

Usage

• Path is the script’s only input. This is a string field that will take the name of the disk file to scan. I didn’t test it, but based on my understanding of PowerShell, piping a string array to it that contains multiple file names should cause the script to run against each of them.

If the targeted file name has a parent, its complete path name will be returned as a string. If it doesn’t, the script will return nothing. The entire script is encapsulated in a single try block whose main purpose is to ensure that the targeted file is closed under any circumstances. Errors from earlier sections will be rethrown. If you call this script from one of your own, consider encapsulating it in a try block with -ErrorAction Stop.

Because this script was intended for use with the above script that does its own extensive validation, I didn’t bother with any validation of -Path. The script will fail predictably even without such checks so it’s not strictly necessary.

<#
.SYNOPSIS
Finds the parent of a differencing disk in environments where Get-VHD is not available.

.DESCRIPTION
Uses .Net functions to read a .VHD or .VHDX file to determine if it has a parent.
This is useful on computers that don't (or can't) have the Hyper-V role installed.

.PARAMETER Path
The path to the .VHD or .VHDX file to be scanned. Due to a .Net limitation, you cannot supply raw volume identifiers. You must use a drive letter or a share.

.OUTPUTS
A string containing the absolute path to the parent, or null if none exists.

.NOTES
Author: Eric Siron
Copyright: (C) 2014 Altaro Software
Version 1.1
Authored Date: October 25, 2014

Comments in this file are sparse because they more or less follow along directly from the specification documents.
VHD specification: http://www.microsoft.com/en-us/download/details.aspx?id=23850
VHDX 1.0 specification: http://www.microsoft.com/en-us/download/details.aspx?id=34750

1.1 December 13,2015
--------------------
* Changed suggested function name to Get-VHDDifferencingParent to be more consistent with existing VM cmdlet
* Added a check for the presence of Get-VHD; if available, will use that instead of the more complicated method
* Added more granular error-checking; not much can actually be done about errors, but they'll be reported more accurately

.LINK
Free Script: Find Orphaned Hyper-V VM Files


.EXAMPLE
C:PS> .Get-VHDDifferencingParent -Path C:TestVHDsdiff1.vhdx

Description
-----------
Retrieves the parent disk of C:TestVHDsdiff1.vhdx, if any.
#>

param(
	[Parameter(Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true)][String]$Path
)

$AbsolutePath = ""
$IdentifierSize = 8
$IdentifierBytes = New-Object Byte[] $IdentifierSize

try # the easy way first
{
	Get-Command -Name Get-VHD -ErrorAction Stop
	try
	{
		(Get-VHD -Path $Path -ErrorAction Stop).ParentPath
		return
	}
	catch
	{
		# probably means we have to try something harder, but let the next section worry about that
	}
}
catch
{
	# just means we have to try something harder
}
try
{
	try
	{
		$VHDStream = New-Object System.IO.FileStream($Path, [System.IO.FileMode]::Open, [System.IO.FileAccess]::Read, [System.IO.FileShare]::ReadWrite) -ErrorAction Stop
	}
	catch
	{
		throw ("Unable to open differencing disk {0} to determine its parent: {1}" -f $Path, $_)
	}

	try
	{
		$BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize)
	}
	catch
	{
		throw ("Unable to read the VHD type identifier for {0}: {1}" -f $Path, $_)
	}

			if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "vhdxfile")
	{
		$1stRegionOffset = 196608; $1stRegionEntryCount = 0; $2ndRegionOffset = 262144; $2ndRegionEntryCount = 0
		$SignatureSize = 4; $EntryCountSize = 8; $GUIDSize = 16; $EntryOffsetSize = 8; $EntryLengthSize = 4
		$ShortEntrySize = 2; $MetadataOffsetSize = 4; $KeyValueCountSize = 2; $LocatorEntrySize = 12
		$SignatureBytes = New-Object Byte[] $SignatureSize; $EntryCountBytes = New-Object Byte[] $EntryCountSize
		$GUIDBytes = New-Object Byte[] $GUIDSize; $EntryOffset = New-Object Byte[] $EntryOffsetSize
		$ShortEntryBytes = New-Object Byte[] $ShortEntrySize; $MetadataOffsetBytes = New-Object Byte[] $MetadataOffsetSize
		$KeyValueCountBytes = New-Object Byte[] $KeyValueCountSize; $LocatorEntryBytes = New-Object Byte[] $LocatorEntrySize
		$LocatorEntries = @()

		($1stRegionOffset, $2ndRegionOffset) | foreach {
			$VHDStream.Position = $_
			try
			{
				$BytesRead = $VHDStream.Read($SignatureBytes, 0, $SignatureSize)
			}
			catch
			{
				throw ("Unable to read signature from header region of {0}: {1}" -f $Path, $_)
			}
			if([System.Text.Encoding]::ASCII.GetString($SignatureBytes) -eq "regi")
			{
				$VHDStream.Position += 4	# jump over the checksum
				try
				{
					$BytesRead = $VHDStream.Read($EntryCountBytes, 0, $EntryCountSize)
				}
				catch
				{
					throw ("Unable to determine number of header entries in {0}: {1}" -f $Path, $_)
				}
				$RegionEntryCount = [System.BitConverter]::ToInt32($EntryCountBytes, 0)
				if($_ = $1stRegionOffset)
				{
					$1stRegionEntryCount = $RegionEntryCount
				}
				else
				{
					$2ndRegionEntryCount = $RegionEntryCount
				}
			}
		}
		if($1stRegionEntryCount -ge $2ndRegionEntryCount)
		{
			$EntryCount = $1stRegionEntryCount
			$StartingEntryOffset = $1stRegionOffset + 16
		}
		else
		{
			$EntryCount = $2ndRegionEntryCount
			$StartingEntryOffset = $2ndRegionOffset + 16
		}

		1..$EntryCount | foreach {
			$VHDStream.Position = $StartingEntryOffset + (32 * ($_ - 1))	# an entry is 32 bytes long
			try
			{
				$BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize)
			}
			catch
			{
				throw ("Unable to retrieve the GUID of a header entry in {0}, {1}" -f $Path, $_)
			}
			if([System.BitConverter]::ToString($GUIDBytes) -eq "06-A2-7C-8B-90-47-9A-4B-B8-FE-57-5F-05-0F-88-6E")	# this is the GUID of a metadata region
			{
				try
				{
					$BytesRead = $VHDStream.Read($EntryOffset, 0, $EntryOffsetSize)
				}
				catch
				{
					throw("Unable to determine the location of a metadata region in {0}: {1}" -f $Path, $_)
				}
				$MetadataStart = $VHDStream.Position = [System.BitConverter]::ToInt64($EntryOffset, 0)

				try
				{
					$BytesRead = $VHDStream.Read($IdentifierBytes, 0, $IdentifierSize)
				}
				catch
				{
					throw("Unable to parse the identifier of an expected metadata region in {0}: {1}"-f $Path, $_)
				}
				if([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "metadata")
				{
					$VHDStream.Position += 2	# jump over reserved field
					try
					{
						$BytesRead = $VHDStream.Read($ShortEntryBytes, 0, $ShortEntrySize)
					}
					catch
					{
						throw("Unable to retrieve the number of header short entries in {0}: {1}" -f $Path, $_)
					}
					$VHDStream.Position += 20	# jump over the rest of the header
					1..([System.BitConverter]::ToUInt16($ShortEntryBytes, 0)) | foreach {
						try
						{
							$BytesRead = $VHDStream.Read($GUIDBytes, 0, $GUIDSize)
						}
						catch
						{
							throw ("Unable to retrieve the GUID of a short entry in {0}: {1}" -f $Path, $_)
						}
						$SavedStreamPosition = $VHDStream.Position
						switch([System.BitConverter]::ToString($GUIDBytes))
						{	## We're only watching for a single item so an "if" could do this, but switch is future-proofing.
							## Should be able to query 37-67-A1-CA-36-FA-43-4D-B3-B6-33-F0-AA-44-E7-6B for a "HasParent" value, but either the documentation is wrong or the implementation is broken as this field holds the same value for all disk types
							"2D-5F-D3-A8-0B-B3-4D-45-AB-F7-D3-D8-48-34-AB-0C" {	# Parent Locator
								try
								{
									$BytesRead = $VHDStream.Read($MetadataOffsetBytes, 0, $MetadataOffsetSize)
								}
								catch
								{
									throw ("Unable to read the location of a metadata entry in {0}: {1}" -f $Path, $_)
								}

								if($BytesRead)
								{
									$ParentLocatorOffset = $MetadataStart + [System.BitConverter]::ToInt32($MetadataOffsetBytes, 0)
									$VHDStream.Position = $ParentLocatorOffset + 18 # jump over the GUID and reserved fields

									try
									{
										$BytesRead = $VHDStream.Read($KeyValueCountBytes, 0, $KeyValueCountSize)
									}
									catch
									{
										throw("Unable to read the number of key/value metadata sets in {0}: {1}" -f $Path, $_)
									}
									if($BytesRead)
									{
										1..[System.BitConverter]::ToUInt16($KeyValueCountBytes, 0) | foreach {
											try
											{
												$BytesRead = $VHDStream.Read($LocatorEntryBytes, 0, $LocatorEntrySize)
											}
											catch
											{
												throw ("Unable to retrieve a key/value metadata set from {0}: {1}" -f $Path, $_)
											}
											if($BytesRead)
											{
												$KeyOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 0)
												$ValueOffset = [System.BitConverter]::ToUInt32($LocatorEntryBytes, 4)
												$KeyLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 8)
												$ValueLength = [System.BitConverter]::ToUInt16($LocatorEntryBytes, 10)
												$LocatorEntries += [String]::Join(",", ($KeyOffset, $ValueOffset, $KeyLength, $ValueLength))
											}
										}
										foreach($Locator in $LocatorEntries)
										{
											$KeyValueSet = $Locator.Split(",")
											$KeyPosition = $ParentLocatorOffset + $KeyValueSet[0]
											$ValuePosition = $ParentLocatorOffset + $KeyValueSet[1]
											$KeyBytes = New-Object Byte[] $KeyValueSet[2]
											$ValueBytes = New-Object Byte[] $KeyValueSet[3]
											$VHDStream.Position = $KeyPosition

											try
											{
												# NOTE: we don't actually do anything with the key, technically could move the pointer past it to the value
												$BytesRead = $VHDStream.Read($KeyBytes, 0, $KeyBytes.Length)
											}
											catch
											{
												throw ("Unable to retrieve the parent path key in the key/value set of {0}: {1}")
											}
											if($BytesRead)
											{
												if([System.Text.Encoding]::Unicode.GetString($KeyBytes) -eq "absolute_win32_path")
												{
													try
													{
														$BytesRead = $VHDStream.Read($ValueBytes, 0, $ValueBytes.Length)
													}
													catch
													{
														throw ("Unable to retrieve the parent path value in the key/value set of {0}: {1}")
													}
													if($BytesRead)
													{
														$AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ValueBytes)
														break
													}
												}
											}
										}
									}
								}
							}
						}
						# move to the start of the next entry
						$VHDStream.Position = $SavedStreamPosition + 16
					}
				}
			}
		}
	}
	elseif([System.Text.Encoding]::ASCII.GetString($IdentifierBytes) -eq "conectix") # this is a VHD file
	{
		$TypeSize = 4; $ChunkSize = 2
		$TypeBytes = New-Object Byte[] $TypeSize -ErrorAction Stop; $ChunkBytes = New-Object Byte[] $ChunkSize -ErrorAction Stop
		$ReverseParentBytes = [Byte[]]@()
		$VHDStream.Position = 60	# this is where the disk type is stored
		try
		{
			$BytesRead = $VHDStream.Read($TypeBytes, 0, $TypeSize)
		}
		catch
		{
			throw ("Unable to determine the disk type of {0}: {1}" -f $Path, $_)
		}
		if($BytesRead)
		{
			[Array]::Reverse($TypeBytes)	# surprise byte reversal!
			if([System.BitConverter]::ToUInt32($TypeBytes, 0) -eq 4)	# is the differencing type
			{
				$VHDStream.Position = 576	# this is where the name of the parent is stored, if any
				1..256 | foreach {	# there are 512 bytes in the name, but they're also reversed. this is much more miserable to fix
					try
					{
						$BytesRead = $VHDStream.Read($ChunkBytes, 0, $ChunkSize)
					}
					catch
					{
						throw ("Unable to read the parent of {0}: {1}" -f $Path, $_)
					}
					if($BytesRead)
					{
						[Array]::Reverse($ChunkBytes)
						$ReverseParentBytes += $ChunkBytes
					}
				}
				$AbsolutePath = [System.Text.Encoding]::Unicode.GetString($ReverseParentBytes) -replace "(?<=.vhd).*"	# remove leftover noise
			}
		}
	}
	else
	{
		throw ("{0} is not a valid VHD(X) file or has a damaged header" -f $Path)
	}
}
catch
{	<#
		PowerShell does not implement any form of "goto" or "using", so the purpose of this outer try block is to simulate goto functionality with an ending point
		that ensures that the file is always closed, if one was opened. otherwise, PS's normal erroring is sufficient
	#>
	throw($_)
}
finally
{
	if($VHDStream)
	{
		$VHDStream.Close()
	}
}
$AbsolutePath