Set-HyperVVMComPort

Hyper-V: Configures COM port settings for a virtual machine

Script

#Requires -Version 5.1
#Requires -Modules Hyper-V

[CmdletBinding()]
Param (
    [string]$ComputerName = "localhost",

    [PSCredential]$Credential,

    [Parameter(Mandatory = $true)]
    [string]$Name,

    [Parameter(Mandatory = $true)]
    [ValidateSet(1, 2)]
    [int]$Number,

    [string]$Path,

    [bool]$DebuggerMode
)

Process {
    try {
        $params = @{
            'ComputerName' = $ComputerName
            'ErrorAction'  = 'Stop'
        }
        if ($Credential) { $params.Add('Credential', $Credential) }

        $vm = Get-VM @params | Where-Object { $_.Name -eq $Name -or $_.Id -eq $Name }

        if (-not $vm) {
            throw "Virtual machine '$Name' not found on '$ComputerName'."
        }

        $comParams = @{ 'VM' = $vm; 'Number' = $Number; 'ErrorAction' = 'Stop' }
        if ($Path) { $comParams.Add('Path', $Path) }
        else { $comParams.Add('Path', $null) } # Disconnect

        if ($PSBoundParameters.ContainsKey('DebuggerMode')) {
            $comParams.Add('DebuggerMode', [string]$DebuggerMode)
        }

        Set-VMComPort @comParams

        $result = [PSCustomObject]@{
            VMName       = $vm.Name
            ComPort      = $Number
            Path         = (Get-VMComPort -VM $vm -Number $Number).Path
            DebuggerMode = (Get-VMComPort -VM $vm -Number $Number).DebuggerMode
            Action       = "ComPortConfigUpdated"
            Status       = "Success"
            Timestamp    = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        }

        Write-Output $result
    }
    catch {
        throw
    }
}

Customize

ComputerName string

Specifies the name of the Hyper-V host. Defaults to the local machine.

Credential PSCredential

Specifies the credentials to use for the remote connection.

Name string

Specifies the name or ID of the virtual machine.

Number int

Specifies the COM port number (1 or 2).

Path string

Optional. Specifies the path to a named pipe (e.g., \\.\pipe\TestPipe). If empty, the port is disconnected.

DebuggerMode bool

Optional. Specifies whether the COM port is enabled for use by debuggers ($true) or disabled ($false).