Set-SCVirtualCOMPort

Syntax

Set-SCVirtualCOMPort
   [-VMMServer <ServerConnection>]
   -GuestPort <Byte>
   -VMHostCOMPort <Byte>
   [-WaitForModem <Boolean>]
   -JobGroup <Guid>
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VMMServer <ServerConnection>]
   -GuestPort <Byte>
   -TextFile <String>
   -JobGroup <Guid>
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VMMServer <ServerConnection>]
   -GuestPort <Byte>
   [-NoAttach]
   -JobGroup <Guid>
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VMMServer <ServerConnection>]
   -GuestPort <Byte>
   -NamedPipe <String>
   -JobGroup <Guid>
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VirtualCOMPort] <VirtualCOMPort>
   -TextFile <String>
   [-JobGroup <Guid>]
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VirtualCOMPort] <VirtualCOMPort>
   [-NoAttach]
   [-JobGroup <Guid>]
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VirtualCOMPort] <VirtualCOMPort>
   -VMHostCOMPort <Byte>
   [-WaitForModem <Boolean>]
   [-JobGroup <Guid>]
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Set-SCVirtualCOMPort
   [-VirtualCOMPort] <VirtualCOMPort>
   -NamedPipe <String>
   [-JobGroup <Guid>]
   [-RunAsynchronously]
   [-PROTipID <Guid>]
   [-JobVariable <String>]
   [<CommonParameters>]

Description

The Set-SCVirtualCOMPort cmdlet modifies one or more properties of a virtual communications (COM) port. A virtual COM port is part of a virtual machine, virtual machine template, or hardware profile used in a Virtual Machine Manager (VMM) environment. Specify a COM port by using the VirtualCOMPort parameter or specify a virtual COM port ID for the GuestPort parameter. Valid values for GuestPort are zero (0) and one (1).

This cmdlet can connect a virtual COM port to a physical COM port, to a text file, or to a named pipe. This cmdlet can disconnect a virtual COM port. If you connect a virtual COM port on a virtual machine to a physical COM port on its host, the virtual machine can use the physical COM port for input and output. The host types support the following virtual COM port connection types:

• Hyper-V. Connects to a named pipe only.
• VMware ESX. Connects to a physical COM port, text file, or named pipe.
• Citrix XenServer. Not Supported.

The WaitForModem parameter specifies whether a virtual COM port on a virtual machine connects immediately to a physical COM port on the host when the virtual machine starts.

If you specify a value of $True for WaitForModem, the virtual machine attempts to connect to the physical COM port on the host only if a program that runs on the virtual machine sends a modem command to the physical COM port. If the COM port on the host is already connected, the virtual machine cannot connect to it. If the virtual machine successfully connects to the physical COM port, the virtual machine later releases the physical COM port back to the host operating system if the program on the virtual machine that uses the COM port stops using the COM port.

If you specify a value of $False for WaitForModem, the virtual machine attempts to connect to the physical COM port on the host as soon as the virtual machine starts. If the COM port on the host is already captured, the virtual machine cannot connect to it. This is the same behavior as for a value of $True. If the virtual machine successfully connects to the physical COM port, the virtual machine does not release the physical COM port back to the host operating system until the virtual machine is shut down.

Examples

Example 1: Connect a virtual COM port to a named pipe

PS C:\> $VM = Get-SCVirtualMachine -Name "VM02"
PS C:\> $COM1 = Get-SCVirtualCOMPort -VM $VM | where {$_.Name -eq "COM1"}
PS C:\> Set-SCVirtualCOMPort -VirtualCOMPort $COM1 -NamedPipe "\\Contoso\Pipe\PipeName"

The first command gets the virtual machine named VM02, and then stores that object in the $VM variable.

The second command gets the virtual COM port named COM1 from VM02, and then stores that object in the $COM1 variable.

The last command connects the virtual COM port in $COM1 to the named pipe \Contoso\Pipe\PipeName.

Example 2: Disconnect a virtual COM port

PS C:\> $VM = Get-SCVirtualMachine -Name "VM04"
PS C:\> $COM1 = Get-SCVirtualCOMPort -VM $VM | where {$_.Name -eq "COM1"}
PS C:\> Set-SCVirtualCOMPort -VirtualCOMPort $COM1 -NoAttach

The first command gets the virtual machine named VM04, and then stores that object in the $VM variable.

The second command gets the virtual COM port on VM04 named COM1, and then stores that object in the $COM1 variable.

The last command specifies the NoAttach parameter. This causes the command to disconnect the virtual COM port in $COM1. You can use this command to disconnect a virtual COM port that is currently connected to a physical COM port on a host, to a named pipe, or to a text file.

Parameters

-GuestPort

-JobGroup

-JobVariable

-NamedPipe

-NoAttach

-PROTipID

-RunAsynchronously

-TextFile

-VirtualCOMPort

-VMHostCOMPort

-VMMServer

-WaitForModem

Outputs

VirtualCOMPort

This cmdlet returns a VirtualCOMPort object.

Notes

• Requires a VMM virtual COM port object. You can retrieve this object by using the Get-SCVirtualCOMPort cmdlet.

Related Links

• Get-SCVirtualCOMPort
• Get-SCVirtualMachine