Set-SCVirtualCOMPort
Set-SCVirtualCOMPort
Changes properties of a virtual COM port associated with a virtual machine, virtual machine template, or hardware profile.
Syntax
Parameter Set: NamedPipe
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -NamedPipe <String> [-JobGroup <Guid]> ] [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [ <CommonParameters>]
Parameter Set: NewParentJobGroupHostPort
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid]> -VMHostCOMPort <Byte]> [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [-WaitForModem <Boolean]> ] [ <CommonParameters>]
Parameter Set: NewParentJobGroupNamedPipe
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid]> -NamedPipe <String> [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]
Parameter Set: NewParentJobGroupNoAttach
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid]> -NoAttach [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]
Parameter Set: NewParentJobGroupTextFile
Set-SCVirtualCOMPort -GuestPort <Byte> -JobGroup <Guid]> -TextFile <String> [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [-VMMServer <ServerConnection> ] [ <CommonParameters>]
Parameter Set: NoAttach
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -NoAttach [-JobGroup <Guid]> ] [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [ <CommonParameters>]
Parameter Set: TextFile
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -TextFile <String> [-JobGroup <Guid]> ] [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [ <CommonParameters>]
Parameter Set: VMHostCOMPort
Set-SCVirtualCOMPort [-VirtualCOMPort] <VirtualCOMPort> -VMHostCOMPort <Byte]> [-JobGroup <Guid]> ] [-JobVariable <String> ] [-PROTipID <Guid]> ] [-RunAsynchronously] [-WaitForModem <Boolean]> ] [ <CommonParameters>]
Detailed Description
The Set-SCVirtualCOMPort cmdlet changes one or more properties of a virtual communications (COM) port associated with a virtual machine, virtual machine template, or hardware profile used in a Virtual Machine Manager (VMM) environment.
Depending on the type of host on which a virtual machine is, or will be, deployed, you can use Set-SCVirtualCOMPort to connect a virtual COM port to a physical COM port on a host server, to a text file, or to a named pipe, or you can use it to disconnect a virtual COM port. Connecting a virtual COM port on a virtual machine to a physical COM port on its host lets the virtual machine use the physical COM port for input and output.
Available Virtual COM Port Connection Types for hosts:
-- 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.
You can use the Set-SCVirtualCOMPort cmdlet with the WaitForModem parameter to specify whether a virtual COM port on a virtual machine will connect immediately to a physical COM port on the host when the virtual machine starts.
If WaitForModem is set to $True, the virtual machine attempts to connect to the physical COM port on the host only when a program running 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 will later release 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 WaitForModem is set to $False, 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 (same behavior as for $True). If the virtual machine successfully connects to the physical COM port, the virtual machine will not release the physical COM port back to the host operating system until the virtual machine is shut down (behavior for $False differs from behavior for $True).
The Set-SCVirtalCOMPort cmdlet uses the VirtualCOMPort parameter and the GuestPort parameter as follows:
-- VirtualCOMPort <VirtualCOMPort>
Used with four Set-SCVirtualCOMPort parameter sets of to specify a VirtualCOMPort object.
-- GuestPort <Byte>
Used with four alternate Set-SCVirtualCOMPort parameter sets to specify a virtual COM port by ID (0 or 1).
Review the syntax information for Set-SCVirtualCOMPort to see which parameter sets use the VirtualCOMPort parameter and which use the GuestPort parameter.
Parameters
-GuestPort<Byte>
Specifies a virtual COM port on a virtual machine by a numerical identifier. Valid values are: 0 or 1.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByValue) |
Accept Wildcard Characters? |
false |
-JobGroup<Guid]>
Specifies an identifier for a series of commands that will run as a set just before the final command that includes the same job group identifier runs.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-JobVariable<String>
Specifies that job progress is tracked and stored in the variable named by this parameter.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-NamedPipe<String>
Specifies a named pipe to which to connect a virtual COM port. Typical uses include creating a connection between a virtual machine and a debugging program on the host (if the debugger supports the use of named pipes), or creating a virtual null modem cable between two virtual machines.
Example named pipe path: \\.\Contoso\Pipe\PipeName
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-NoAttach
Specifies that no physical COM port on a host, named pipe, or file will be connected to a virtual COM port; or disconnects a virtual COM port that is already connected to a physical COM port to a named pipe, or to a text file.
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-PROTipID<Guid]>
Specifies the ID of the PRO tip that triggered this action. This allows for auditing of PRO tips.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-RunAsynchronously
Indicates that the job runs asynchronously so that control returns to the command shell immediately.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-TextFile<String>
Specifies a text file on the host to which to connect a virtual COM port on a virtual machine so that output from the virtual COM port can be sent to that text file. The text file can be on any valid disk drive on the host.
Example format: -TextFile "D:\ComPort.txt"
Aliases |
none |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-VirtualCOMPort<VirtualCOMPort>
Specifies a virtual COM port object. VMM supports configuring two COM ports on a virtual machine, template, or hardware profile.
Aliases |
none |
Required? |
true |
Position? |
1 |
Default Value |
none |
Accept Pipeline Input? |
True (ByValue) |
Accept Wildcard Characters? |
false |
-VMHostCOMPort<Byte]>
Specifies a physical COM port object on a host server to which you can connect a virtual COM port.
Aliases |
HostPort |
Required? |
true |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
-VMMServer<ServerConnection>
Specifies a VMM server object.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
True (ByValue) |
Accept Wildcard Characters? |
false |
-WaitForModem<Boolean]>
Specifies, when set to $True, that a virtual COM port will wait to connect to a physical COM port on the host, or, when set to $False, that the virtual COM port will connect immediately to a physical COM port on the host as soon as the virtual machine starts.
Aliases |
none |
Required? |
false |
Position? |
named |
Default Value |
none |
Accept Pipeline Input? |
false |
Accept Wildcard Characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/p/?LinkID=113216).
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
Outputs
The output type is the type of the objects that the cmdlet emits.
- VirtualCOMPort
Notes
- This cmdlet requires a VMM virtual COM port object. You can retrieve this object by using the Get-SCVirtualCOMPort cmdlet.
Examples
Example 1: Connect a virtual COM port to a named pipe
The first command gets the virtual machine object named VM02, and then stores the object in the $VM variable.
The second command gets the virtual COM port named COM1 from VM02, and then stores the object in the $COM1 variable.
The last command connects the virtual COM port to the named pipe \\Contoso\Pipe\PipeName.
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"
Example 2: Disconnect a virtual COM port
The first command gets the virtual machine object named VM04, and then stores the object in the $VM variable.
The second command gets the virtual COM port on VM04 named COM1, and then stores the port object in the $COM1 variable.
The last command disconnects the virtual COM port object in $COM1 by specifying the NoAttach parameter.
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.
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