VMWare's vmrun.exe wrapper

    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' A wrapper of VmWare's vmrun.exe application.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <example> This is a code example that demonstrates how to get the running virtual machines, then run a program on each guest operating system.
    ''' <code>
    ''' Private vmRun As VmRunWrapper
    '''
    ''' Private Async Sub Test()
    '''
    '''     Me.vmRun = New VmRunWrapper("C:\Program Files (x86)\VMWare\VMware VIX\vmrun.exe")
    '''
    '''     Dim vmCount As Integer = Await Me.vmRun.GetRunningVmCountAsync()
    '''     If (vmCount > 0) Then
    '''
    '''         Dim vms As ReadOnlyCollection(Of VMWareVirtualMachine) = Await Me.vmRun.GetRunningVmsAsync()
    '''
    '''         For Each vm As VMWareVirtualMachine In vms
    '''
    '''             ' Check whether VMWare-Tools are installed in the VM.
    '''             ' The VmWare-Tools are required by some of the functionalities of vmrun.exe program.
    '''             Dim isVMWareToolsInstalled As Boolean = Await Me.vmRun.IsVmWareToolsInstalledAsync(vm)
    '''             Console.WriteLine("VM Name: {0}; IsVMWareToolsInstalled: {1}'", vm.DisplayName, isVMWareToolsInstalled)
    '''
    '''             If Not isVMWareToolsInstalled Then
    '''                 Me.vmRun.InstallVmWareTools(vm)
    '''                 Continue For
    '''             End If
    '''
    '''             ' A valid guest username and password (if any) is required in order to use some of the functionalities of vmrun.exe program.
    '''             vm.GuestOsCredential.Username = "guest username"
    '''             vm.GuestOsCredential.Password = "guest password"
    '''
    '''             Try
    '''                 ' Run a random program on the guest operating system.
    '''                 Me.vmRun.ProcessRun(vm, "C:\program.exe", VmRunProgramFlags.NoWait Or VmRunProgramFlags.ActiveWindow Or VmRunProgramFlags.Interactive, "")
    '''
    '''             Catch ex As VmRunException
    '''                 Throw
    '''
    '''             Catch ex As Exception
    '''                 Throw
    '''
    '''             End Try
    '''
    '''         Next
    '''
    '''     End If
    '''
    ''' End Sub
    ''' </code>
    ''' </example>
    ''' ----------------------------------------------------------------------------------------------------
    <ImmutableObject(True)>
    Public NotInheritable Class VmRunWrapper : Implements IDisposable

#Region " Properties "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the <c>VmRun.exe</c> file path.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public ReadOnly Property FilePath As String

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets a value indicating whether the <c>VmRun.exe</c> file Exists.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public ReadOnly Property Exists As Boolean
            Get
                Return File.Exists(Me.FilePath)
            End Get
        End Property

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the <c>VmRun.exe</c> <see cref="Diagnostics.Process"/> instance.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public ReadOnly Property Process As Process

#End Region

#Region " Constructors "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Prevents a default instance of the <see cref="VmRunWrapper"/> class from being created.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private Sub New()
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="VmRunWrapper"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="filepath">
        ''' The <c>VmRun.exe</c> filepath.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub New(ByVal filepath As String)

            Me.FilePath = filepath

            Me.Process =
                New Process With {.StartInfo =
                    New ProcessStartInfo With {
                        .FileName = filepath,
                        .CreateNoWindow = True,
                        .UseShellExecute = False,
                        .RedirectStandardError = False,
                        .RedirectStandardOutput = True
                    }
                }

        End Sub

#End Region

#Region " Public Methods "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the amount of virtual machines that are running on the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The amount of virtual machines that are running on the host operating system.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetRunningVmCount() As Integer
            Dim stdOut As String = Me.RunProcess("-T ws list")
            Dim line As String = stdOut.Split({Environment.NewLine}, StringSplitOptions.RemoveEmptyEntries).First()
            Dim count As Integer = CInt(line.Replace("Total running VMs: ", ""))

            Return count
        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets the amount of virtual machines that are running on the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The amount of virtual machines that are running on the host operating system.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetRunningVmCountAsync() As Task(Of Integer)

            Dim t As New Task(Of Integer)(AddressOf Me.GetRunningVmCount)
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the file paths of the virtual machines that are running on the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The file paths of the virtual machines that are running on the host operating system.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetRunningVms() As ReadOnlyCollection(Of VMWareVirtualMachine)

            Dim vms As New Collection(Of VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess("-T ws list")

            For Each line As String In stdOut.Split({Environment.NewLine}, StringSplitOptions.RemoveEmptyEntries)
                If Not line.StartsWith("Total running VMs:", StringComparison.OrdinalIgnoreCase) Then
                    Dim filepath As String = line
                    Dim vm As New VMWareVirtualMachine(filepath, isSharedVm:=False)
                    vms.Add(vm)
                End If
            Next line

            Return New ReadOnlyCollection(Of VMWareVirtualMachine)(vms)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets the file paths of the virtual machines that are running on the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The file paths of the virtual machines that are running on the host operating system.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetRunningVmsAsync() As Task(Of ReadOnlyCollection(Of VMWareVirtualMachine))

            Dim t As New Task(Of ReadOnlyCollection(Of VMWareVirtualMachine))(AddressOf Me.GetRunningVms)
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the amount of snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The amount of snapshots created.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetSnapshotCount(ByVal vm As VMWareVirtualMachine) As Integer
            Dim stdOut As String = Me.RunProcess(String.Format("-T ws listSnapshots ""{0}""", vm.VmxFile.FullName))
            Dim line As String = stdOut.Split({Environment.NewLine}, StringSplitOptions.RemoveEmptyEntries).First()
            Dim count As Integer = CInt(line.Replace("Total snapshots: ", ""))

            Return count
        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets the amount of snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The amount of snapshots created.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetSnapshotCountAsync(ByVal vm As VMWareVirtualMachine) As Task(Of Integer)

            Dim t As New Task(Of Integer)(Function() Me.GetSnapshotCount(vm))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the names of the snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The snapshot names.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetSnapshotNames(ByVal vm As VMWareVirtualMachine) As ReadOnlyCollection(Of String)

            Dim names As New Collection(Of String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws listSnapshots ""{0}""", vm.VmxFile.FullName))

            For Each line As String In stdOut.Split({Environment.NewLine}, StringSplitOptions.RemoveEmptyEntries)
                If Not line.StartsWith("Total snapshots:", StringComparison.OrdinalIgnoreCase) Then
                    Dim name As String = line
                    names.add(name)
                End If
            Next line

            Return New ReadOnlyCollection(Of String)(names)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets the names of the snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The snapshot names.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetSnapshotNamesAsync(ByVal vm As VMWareVirtualMachine) As Task(Of ReadOnlyCollection(Of String))

            Dim t As New Task(Of ReadOnlyCollection(Of String))(Function() Me.GetSnapshotNames(vm))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets a tree-view of the snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' A tree-view of the snapshots.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetSnapshotsTreeview(ByVal vm As VMWareVirtualMachine) As String

            Dim sb As New StringBuilder()

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws listSnapshots ""{0}"" showTree", vm.VmxFile.FullName))

            For Each line As String In stdOut.Split({Environment.NewLine}, StringSplitOptions.RemoveEmptyEntries)
                If Not line.StartsWith("Total snapshots:", StringComparison.OrdinalIgnoreCase) Then
                    sb.AppendLine(line)
                End If
            Next line

            Return sb.ToString()

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets a tree-view of the snapshots created in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' A tree-view of the snapshots.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetSnapshotsTreeviewAsync(ByVal vm As VMWareVirtualMachine) As Task(Of String)

            Dim t As New Task(Of String)(Function() Me.GetSnapshotsTreeview(vm))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets a value that determine whether VmWare Tools is installed in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if VmWare Tools is installed in the specified virtual machine; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function IsVmWareToolsInstalled(ByVal vm As VMWareVirtualMachine) As Boolean

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws checkToolsState ""{0}""", vm.VmxFile.FullName))

            Return stdOut.Equals("installed", StringComparison.OrdinalIgnoreCase) OrElse
                   stdOut.Equals("running", StringComparison.OrdinalIgnoreCase)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets a value that determine whether VmWare Tools is installed in the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if VmWare Tools is installed in the specified virtual machine; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function IsVmWareToolsInstalledAsync(ByVal vm As VMWareVirtualMachine) As Task(Of Boolean)

            Dim t As New Task(Of Boolean)(Function() Me.IsVmWareToolsInstalled(vm))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Start the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="noGui">
        ''' A value indicating whether to start the virtual machine with VmWare GUI or not.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmStart(ByVal vm As VMWareVirtualMachine, ByVal noGui As Boolean)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws start ""{0}"" {1}", vm.VmxFile.FullName, If(noGui, "nogui", "gui")))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Stop the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="hardStop">
        ''' A value indicating whether to perform a hard or soft stop.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmStop(ByVal vm As VMWareVirtualMachine, ByVal hardStop As Boolean)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws stop ""{0}"" {1}", vm.VmxFile.FullName, If(hardStop, "hard", "soft")))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Reset the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="hardReset">
        ''' A value indicating whether to perform a hard or soft reset.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmReset(ByVal vm As VMWareVirtualMachine, ByVal hardReset As Boolean)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws reset ""{0}"" {1}", vm.VmxFile.FullName, If(hardReset, "hard", "soft")))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Suspend the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="hardSuspend">
        ''' A value indicating whether to perform a hard or soft suspend.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmSuspend(ByVal vm As VMWareVirtualMachine, ByVal hardSuspend As Boolean)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws suspend ""{0}"" {1}", vm.VmxFile.FullName, If(hardSuspend, "hard", "soft")))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Pause the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmPause(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws pause ""{0}""", vm.VmxFile.FullName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Resume (unpause) the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmResume(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws unpause ""{0}""", vm.VmxFile.FullName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Deletes the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub VmDelete(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws deleteVm ""{0}""", vm.VmxFile.FullName))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Create a snapshot of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="name">
        ''' The snapshot name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SnapshotCreate(ByVal vm As VMWareVirtualMachine, ByVal name As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws snapshot ""{0}"" ""{1}""", vm.VmxFile.FullName, name))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Delete a snapshot from the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="name">
        ''' The snapshot name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SnapshotDelete(ByVal vm As VMWareVirtualMachine, ByVal name As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws deleteSnapshot ""{0}"" ""{1}""", vm.VmxFile.FullName, name))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Revert the state of the specified virtual machine to the state of the specified snapshot.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="name">
        ''' The snapshot name.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SnapshotRestore(ByVal vm As VMWareVirtualMachine, ByVal name As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws revertToSnapshot ""{0}"" ""{1}""", vm.VmxFile.FullName, name))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Determine whether a file exists in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="filepath">
        ''' The full path to a existing file in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if the file exists in the guest operating system; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function FileExists(ByVal vm As VMWareVirtualMachine, ByVal filepath As String) As Boolean

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" fileExistsInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, filepath))

            Return stdOut.Equals("The file exists.", StringComparison.OrdinalIgnoreCase)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously determine whether a file exists in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="filepath">
        ''' The full path to a existing file in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if the file exists in the guest operating system; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function FileExistsAsync(ByVal vm As VMWareVirtualMachine, ByVal filepath As String) As Task(Of Boolean)

            Dim t As New Task(Of Boolean)(Function() Me.FileExists(vm, filepath))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Determine whether a directory exists in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="directoryPath">
        ''' The full path to a existing file in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if the directory exists in the guest operating system; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function DirectoryExists(ByVal vm As VMWareVirtualMachine, ByVal directoryPath As String) As Boolean

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" directoryExistsInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, directoryPath))

            Return stdOut.Equals("The directory exists.", StringComparison.OrdinalIgnoreCase)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously determine whether a directory exists in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="directoryPath">
        ''' The full path to a existing file in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' <see langword="True"/> if the directory exists in the guest operating system; otherwise, <see langword="False"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function DirectoryExistsAsync(ByVal vm As VMWareVirtualMachine, ByVal directoryPath As String) As Task(Of Boolean)

            Dim t As New Task(Of Boolean)(Function() Me.DirectoryExists(vm, directoryPath))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Delete a file from the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="filepath">
        ''' The full path of the file to be deleted in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub FileDelete(ByVal vm As VMWareVirtualMachine, ByVal filepath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" deleteFileInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, filepath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Delete a directory from the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="directoryPath">
        ''' The full path of the directory to be deleted in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub DirectoryDelete(ByVal vm As VMWareVirtualMachine, ByVal directoryPath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" deleteDirectoryInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, directoryPath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Create a directory in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="directoryPath">
        ''' The full path of the directory to be created in the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub DirectoryCreate(ByVal vm As VMWareVirtualMachine, ByVal directoryPath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" createDirectoryInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, directoryPath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Installs VmWare Tools on the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub InstallVmWareTools(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" installTools ""{0}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Rename a file in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="srcFilepath">
        ''' The full path to a existing file in the guest operating system.
        ''' </param>
        '''
        ''' <param name="dstFilepath">
        ''' The new destination path for the file set in the <paramref name="srcFilepath"/> parameter.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub FileRename(ByVal vm As VMWareVirtualMachine, ByVal srcFilepath As String, ByVal dstFilepath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" renameFileInGuest ""{2}"" ""{3}"" ""{4}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, srcFilepath, dstFilepath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Copies a file from the host operating system to the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="hostFilePath">
        ''' The source file path; the file to be copied from the host operating system.
        ''' </param>
        '''
        ''' <param name="guestFilePath">
        ''' The destination file path; the file being copied into the guest operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub FileCopyFromHostToGuest(ByVal vm As VMWareVirtualMachine, ByVal hostFilePath As String, ByVal guestFilePath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" CopyFileFromHostToGuest ""{2}"" ""{3}"" ""{4}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, hostFilePath, guestFilePath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Copies a file from the guest operating system of the specified virtual machine to the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="guestFilePath">
        ''' The source file path; the file to be copied from the guest operating system.
        ''' </param>
        '''
        ''' <param name="hostFilePath">
        ''' The destination file path; the file being copied into the host operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub FileCopyFromGuestToHost(ByVal vm As VMWareVirtualMachine, ByVal guestFilePath As String, ByVal hostFilePath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" CopyFileFromGuestToHost ""{2}"" ""{3}"" ""{4}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, guestFilePath, hostFilePath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Capture the screen of the guest operating system of the specified virtual machine
        ''' and save it to a image file (in .PNG format) in the host operating system.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="hostFilePath">
        ''' The full path to the image file that will be created in the host operating system.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub CaptureScreen(ByVal vm As VMWareVirtualMachine, ByVal hostFilePath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" captureScreen ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, hostFilePath))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets the IP address of the guest operating system on the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The resulting <see cref="IPAddress"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function GetIpAddress(ByVal vm As VMWareVirtualMachine) As IPAddress

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" getGuestIPAddress ""{2}"" -wait",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName))

            Return IPAddress.Parse(stdOut)

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously gets the IP address of the guest operating system on the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The resulting <see cref="IPAddress"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function GetIpAddressAsync(ByVal vm As VMWareVirtualMachine) As Task(Of IPAddress)

            Dim t As New Task(Of IPAddress)(Function() Me.GetIpAddress(vm))
            t.Start()
            Await t
            Return t.Result

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Send keystrokes to the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="keystrokes">
        ''' The keystrokes to send.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SendKeystrokes(ByVal vm As VMWareVirtualMachine, ByVal keystrokes As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" typeKeystrokesInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, keystrokes))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Enable shared folders features in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFoldersEnable(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" enableSharedFolders ""{2}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Enable shared folders features in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFoldersDisable(ByVal vm As VMWareVirtualMachine)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" disableSharedFolders ""{2}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Adds a new shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="shareName">
        ''' The name to assign to the shared folder.
        ''' </param>
        '''
        ''' <param name="hostDirectoryPath">
        ''' The full path to the directory on the host operating system being shared.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderAdd(ByVal vm As VMWareVirtualMachine, ByVal shareName As String, ByVal hostDirectoryPath As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" addSharedFolder ""{2}"" ""{3}"" ""{4}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, shareName, hostDirectoryPath))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Adds a new shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="sharedFolder">
        ''' The sharedFolder being added.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderAdd(ByVal vm As VMWareVirtualMachine, ByVal sharedFolder As VmSharedFolderInfo)

            Me.SharedFolderAdd(vm, sharedFolder.Name, sharedFolder.HostDirectory.FullName)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Adds a new shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="shareName">
        ''' The name of the shared folder being removed.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderRemove(ByVal vm As VMWareVirtualMachine, ByVal shareName As String)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" removeSharedFolder ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, shareName))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Adds a new shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="sharedFolder">
        ''' The sharedFolder being removed.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderRemove(ByVal vm As VMWareVirtualMachine, ByVal sharedFolder As VmSharedFolderInfo)

            Me.SharedFolderRemove(vm, sharedFolder.Name)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Sets the writable/readonly access of a shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="shareName">
        ''' The name of the shared folder.
        ''' </param>
        '''
        ''' <param name="hostDirectoryPath">
        ''' The full path to the directory that points the shared folder on the host operating system.
        ''' </param>
        '''
        ''' <param name="allowWriteAccess">
        ''' If <see langword="True"/>, allow write access to the shared folder; otherwise, make the shared folder read-only.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderSetAccess(ByVal vm As VMWareVirtualMachine, ByVal shareName As String, ByVal hostDirectoryPath As String, ByVal allowWriteAccess As Boolean)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" setSharedFolderState ""{2}"" ""{3}"" ""{4}"" ""{5}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, shareName, hostDirectoryPath,
                                                               If(allowWriteAccess, "writable", "readonly")))

            vm.Refresh()

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Sets the writable/readonly access of a shared folder in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="sharedFolder">
        ''' The shared folder.
        ''' </param>
        '''
        ''' <param name="allowWriteAccess">
        ''' If <see langword="True"/>, allow write access to the shared folder; otherwise, make the shared folder read-only.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub SharedFolderSetAccess(ByVal vm As VMWareVirtualMachine, ByVal sharedFolder As VmSharedFolderInfo, ByVal allowWriteAccess As Boolean)

            Me.SharedFolderSetAccess(vm, sharedFolder.Name, sharedFolder.HostDirectory.FullName, allowWriteAccess)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Kills a running process from the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="pid">
        ''' The process identifier.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub ProcessKill(ByVal vm As VMWareVirtualMachine, ByVal pid As Integer)

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" killProcessInGuest ""{2}"" ""{3}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName, pid))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Runs a new process in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="executablePath">
        ''' The full path to the executable file in the guest operating system.
        ''' </param>
        '''
        ''' <param name="flags">
        ''' Flags that determine the runtime behavior. You can combine the flags.
        ''' </param>
        '''
        ''' <param name="arguments">
        ''' The program arguments.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub ProcessRun(ByVal vm As VMWareVirtualMachine, ByVal executablePath As String, ByVal flags As VmRunProgramFlags, Optional ByVal arguments As String = "")

            Dim flagsFormatted As String = String.Empty
            If Not flags = VmRunProgramFlags.None Then
                flags = (flags And Not VmRunProgramFlags.None)
                flagsFormatted = flags.ToString().Replace(", ", " -").Insert(0, "-"c)
            End If

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" runProgramInGuest ""{2}"" {3} ""{4}"" ""{5}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName,
                                                               flagsFormatted, executablePath, arguments))

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Runs a script in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="interpreterPath">
        ''' The full path to the interpreter executable file in the guest operating system. (eg. "C:\Windows\System32\cscript.exe")
        ''' </param>
        '''
        ''' <param name="flags">
        ''' Flags that determine the runtime behavior. You can combine the flags.
        ''' </param>
        '''
        ''' <param name="scriptContent">
        ''' The text content of the script to run.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function ProcessRunScript(ByVal vm As VMWareVirtualMachine, ByVal interpreterPath As String, ByVal flags As VmRunProgramFlags, ByVal scriptContent As String) As String

            Dim flagsFormatted As String = String.Empty
            If Not flags = VmRunProgramFlags.None Then
                flags = (flags And Not VmRunProgramFlags.None)
                flagsFormatted = flags.ToString().Replace(", ", " -").Insert(0, "-"c)
            End If

            Dim stdOut As String = Me.RunProcess(String.Format("-T ws -gu ""{0}"" -gp ""{1}"" runScriptInGuest ""{2}"" {3} ""{4}"" ""{5}""",
                                                               vm.GuestOsCredential.Username, vm.GuestOsCredential.Password,
                                                               vm.VmxFile.FullName,
                                                               flagsFormatted, interpreterPath, scriptContent))

            Return stdOut

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Asynchronously runs a script in the guest operating system of the specified virtual machine.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="vm">
        ''' The VMWare virtual machine.
        ''' </param>
        '''
        ''' <param name="interpreterPath">
        ''' The full path to the interpreter executable file in the guest operating system. (eg. "C:\Windows\System32\cscript.exe")
        ''' </param>
        '''
        ''' <param name="flags">
        ''' Flags that determine the runtime behavior. You can combine the flags.
        ''' </param>
        '''
        ''' <param name="scriptContent">
        ''' The text content of the script to run.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Async Function ProcessRunScriptAsync(ByVal vm As VMWareVirtualMachine, ByVal interpreterPath As String, ByVal flags As VmRunProgramFlags, ByVal scriptContent As String) As Task(Of String)

            Dim t As New Task(Of String)(Function() Me.ProcessRunScript(vm, interpreterPath, flags, scriptContent))
            t.Start()
            Await t
            Return t.Result

        End Function

#End Region

#Region " Private Methods "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Runs vmrun.exe process with the specified arguments and returns the standard output.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="args">
        ''' The vmrun.exe process arguments.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The standard output of vmrun.exe process.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Function RunProcess(ByVal args As String) As String
            Dim stdOut As String
            Dim exitCode As Integer

            SyncLock Me.Process
                Me.Process.StartInfo.Arguments = args
                Me.Process.Start()
                Me.Process.WaitForExit(Timeout.Infinite)

                stdOut = Me.Process.StandardOutput.ReadToEnd().TrimEnd()
                exitCode = Me.Process.ExitCode
            End SyncLock

            If stdOut.StartsWith("Error:", StringComparison.OrdinalIgnoreCase) Then
                Throw New VmRunException(stdOut, exitCode)
            End If

            Return stdOut
        End Function

#End Region

#Region " IDisposable Implementation "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Flag to detect redundant calls when disposing.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private isDisposed As Boolean = False

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Releases all the resources used by this instance.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub Dispose() Implements IDisposable.Dispose
            Me.Dispose(isDisposing:=True)
            GC.SuppressFinalize(obj:=Me)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="isDisposing">
        ''' <see langword="True"/>  to release both managed and unmanaged resources;
        ''' <see langword="False"/> to release only unmanaged resources.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Sub Dispose(ByVal isDisposing As Boolean)

            If (Not Me.isDisposed) AndAlso (isDisposing) Then

                If (Me.Process IsNot Nothing) Then

                    'Try
                    '    Me.Process.Kill()
                    '
                    'Catch ex As Exception
                    '
                    'End Try

                    Me.Process.Dispose()
                End If

            End If

            Me.isDisposed = True

        End Sub

#End Region

    End Class