ConnectSwitchPort method of the Msvm_VirtualSwitchManagementService class
Connects a switch port to a LAN endpoint. Upon success of the connection, an active connection instance will be created that associates the port with the LAN endpoint.
Syntax
uint32 ConnectSwitchPort(
[in] Msvm_SwitchPort REF SwitchPort,
[in] CIM_LANEndpoint REF LANEndpoint,
[out] Msvm_ActiveConnection REF ActiveConnection
);
Parameters
-
SwitchPort [in]
-
Type: Msvm_SwitchPort
The switch port to be connected to the LAN endpoint. See Msvm_SwitchPort.
-
LANEndpoint [in]
-
Type: CIM_LANEndpoint
The LAN endpoint to be connected to the switch port. See CIM_LANEndpoint.
-
ActiveConnection [out]
-
Type: Msvm_ActiveConnection
Upon successful completion of this method, this parameter contains the created connection association. See Msvm_ActiveConnection.
Return value
Type: uint32
The method returns 0 if it succeeded synchronously. Any other return value indicates an error.
-
Completed with No Error (0)
-
Method Parameters Checked - Job Started (4096)
-
Failed (32768)
-
Access Denied (32769)
-
Not Supported (32770)
-
Status is unknown (32771)
-
Timeout (32772)
-
Invalid parameter (32773)
-
System is in used (32774)
-
Invalid state for this operation (32775)
-
Incorrect data type (32776)
-
System is not available (32777)
-
Out of memory (32778)
Remarks
Access to the Msvm_VirtualSwitchManagementService class might be restricted by UAC Filtering. For more information, see User Account Control and WMI.
Examples
The following C# sample connects a switch port. The referenced utilities can be found in Common Utilities for the Virtualization Samples.
using System;
using System.Management;
namespace HyperVSamples
{
class ConnectSwitchPortClass
{
ManagementObject switchService = null;
ManagementScope scope = null;
ConnectSwitchPortClass()
{
scope = new ManagementScope(@"root\virtualization", null);
switchService = Utility.GetServiceObject(scope, "Msvm_VirtualSwitchManagementService");
}
ManagementObject GetVirtualSwitch(string switchName)
{
string query = string.Format("select * from Msvm_VirtualSwitch where ElementName = '{0}'", switchName);
ManagementObjectSearcher searcher = new ManagementObjectSearcher(scope, new ObjectQuery(query));
ManagementObjectCollection virtualSwitchs = searcher.Get();
ManagementObject virtualSwitch = null;
foreach (ManagementObject instance in virtualSwitchs)
{
virtualSwitch = instance;
break;
}
searcher.Dispose();
return virtualSwitch;
}
ManagementObject GetVirtualSwitchPort(ManagementObject virtualSwitch, string switchPortName)
{
ManagementObjectCollection switchPorts = virtualSwitch.GetRelated
(
"Msvm_SwitchPort",
"Msvm_HostedAccessPoint",
null,
null,
"Dependent",
"Antecedent",
false,
null
);
ManagementObject switchPort = null;
foreach (ManagementObject instance in switchPorts)
{
if (instance["ElementName"].ToString().ToLower() == switchPortName.ToLower())
{
switchPort = instance;
break;
}
}
return switchPort;
}
ManagementObject GetVMEthernetPort(string vmName, string vmEthernetPortClass)
{
ManagementObject vmEthernetPort = null;
ManagementObject computerSystem = Utility.GetTargetComputer(vmName, scope);
ManagementObjectCollection vmEthernetPorts = computerSystem.GetRelated
(
vmEthernetPortClass,
"Msvm_SystemDevice",
null,
null,
"PartComponent",
"GroupComponent",
false,
null
);
foreach (ManagementObject instance in vmEthernetPorts)
{
vmEthernetPort = instance;
break;
}
return vmEthernetPort;
}
ManagementObject GetVMLanEndPoint(ManagementObject vmEthernetPort)
{
ManagementObjectCollection vmEndPoints = vmEthernetPort.GetRelated
(
"Msvm_VMLanEndPoint",
"Msvm_DeviceSAPImplementation",
null,
null,
"Dependent",
"Antecedent",
false,
null
);
ManagementObject vmEndPoint = null;
foreach (ManagementObject instance in vmEndPoints)
{
vmEndPoint = instance;
break;
}
return vmEndPoint;
}
void ConnectSwitchPort(ManagementObject switchPort, ManagementObject LanEndPoint)
{
ManagementBaseObject inParams = switchService.GetMethodParameters("ConnectSwitchPort");
inParams["SwitchPort"] = switchPort.Path.Path;
inParams["LANEndpoint"] = LanEndPoint.Path.Path;
ManagementBaseObject outParams = switchService.InvokeMethod("ConnectSwitchPort", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("{0} was connected successfully", switchPort.Path.Path);
}
else
{
Console.WriteLine("Failed to connect {0} switch port.", switchPort.Path.Path);
}
inParams.Dispose();
outParams.Dispose();
switchPort.Dispose();
switchService.Dispose();
}
static void Usage()
{
Console.WriteLine("Usage: ConnectSwitchPort SwitchName SwitchPortName vmName vmNicType");
Console.WriteLine("vmNicType: Synthetic|Emulated");
Console.WriteLine("Example: ConnectSwitchPort {0} \"{1}\" {2} {3}",
"MyFirstSwitch",
"VM Switch Port",
"MyFirstVM",
"Emulated"
);
}
static void Main(string[] args)
{
if (args != null && args.Length != 4)
{
Usage();
return;
}
string switchName = args[0];
string switchPortName = args[1];
string vmName = args[2];
string vmNicType = args[3];
string vmNicClassName = null;
if (vmNicType.ToLower() == "emulated")
{
vmNicClassName = "Msvm_EmulatedEthernetPort";
}
else if (vmNicType.ToLower() == "synthetic")
{
vmNicClassName = "Msvm_SyntheticEthernetPort";
}
else
{
Usage();
}
ConnectSwitchPortClass connectSwitchPort = new ConnectSwitchPortClass();
ManagementObject virtualSwitch = connectSwitchPort.GetVirtualSwitch(switchName);
ManagementObject virtualSwitchPort = connectSwitchPort.GetVirtualSwitchPort(virtualSwitch, switchPortName);
ManagementObject vmNic = connectSwitchPort.GetVMEthernetPort(vmName, vmNicClassName);
ManagementObject vmLanEndPoint = connectSwitchPort.GetVMLanEndPoint(vmNic);
connectSwitchPort.ConnectSwitchPort(virtualSwitchPort, vmLanEndPoint);
virtualSwitch.Dispose();
virtualSwitchPort.Dispose();
vmNic.Dispose();
vmLanEndPoint.Dispose();
}
}
}
The following VBScript sample connects a switch port.
option explicit
dim objWMIService
dim switchService
dim fileSystem
const wmiStarted = 4096
const wmiSuccessful = 0
Main()
'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
dim computer, objArgs
dim switchFriendlyName, switchPortFriendlyName, switch, switchPort
dim vmName, vmEthernetPortType, vmEthernetPortClassName
dim vmEthernetPort, vmEthernetPortEndPoint
set objArgs = WScript.Arguments
if WScript.Arguments.Count = 4 then
switchFriendlyName = objArgs.Unnamed.Item(0)
switchPortFriendlyName = objArgs.Unnamed.Item(1)
vmName = objArgs.Unnamed.Item(2)
vmEthernetPortType = objArgs.Unnamed.Item(3)
vmEthernetPortClassName = GetEthernetPortClassName(vmEthernetPortType)
else
Usage()
end if
set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")
computer = "."
set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")
set switchService = objWMIService.ExecQuery("select * from Msvm_VirtualSwitchManagementService").ItemIndex(0)
set switch = GetVirtualSwitch(switchFriendlyName)
if (switch Is Nothing) then
WriteLog Format1("Unable to find switch {0}", switchFriendlyName)
WScript.Quit(1)
end if
set switchPort = GetVirtualSwitchPort(switch, switchPortFriendlyName)
if (switchPort Is Nothing) then
WriteLog Format1("Unable to find switchPort '{0}'", switchPortFriendlyName)
WScript.Quit(1)
end if
set vmEthernetPort = GetVMEthernetPort(vmName, vmEthernetPortClassName)
if (vmEthernetPort Is Nothing) then
WriteLog Format1("Unable to find VM {0} instance.", vmEthernetPortClassName)
WScript.Quit(1)
end if
set vmEthernetPortEndPoint = GetVMEthernetPortEndPoint(vmEthernetPort)
if (vmEthernetPortEndPoint Is Nothing) then
WriteLog Format1("Unable to find VM {0} endpoint.", vmEthernetPortClassName)
WScript.Quit(1)
end if
if ConnectSwitchPort(switchPort, vmEthernetPortEndPoint) then
WriteLog "Done"
WScript.Quit(0)
else
WriteLog "ConnectSwitchPort failed"
WScript.Quit(1)
end if
End Sub
'-----------------------------------------------------------------
' Display command line help
'-----------------------------------------------------------------
Sub Usage()
WScript.Echo "usage: cscript ConnectSwitchPort SwitchFriendlyName" &_
"SwitchPortFriendlyName vmFriendlyName" &_
"vmEthernetPortType"
WScript.Echo "vmEthernetPortType: Synthetic | Emulated" & vbcrlf
WScript.Echo "Example: cscript ConnectSwitchPort ""First VirtualSwitch"" " &_
"""First VirtualSwitch Port"" MyFirstVM Emulated"
WScript.Quit(1)
End Sub
'-----------------------------------------------------------------
' Get vm Ethernet port WMI class name
'-----------------------------------------------------------------
Function GetEthernetPortClassName(vmEthernetportType)
if lcase(vmEthernetPortType) = "emulated" then
GetEthernetPortClassName = "Msvm_EmulatedEthernetPort"
elseif lcase(vmEthernetPortType) = "synthetic" then
GetEthernetPortClassName = "Msvm_SyntheticEthernetPort"
else
usage()
end if
End Function
'-----------------------------------------------------------------
' Retrieve VirtualSwitch
'-----------------------------------------------------------------
Function GetVirtualSwitch(friendlyName)
dim query
set GetVirtualSwitch = Nothing
query = Format1("select * from Msvm_VirtualSwitch where ElementName = '{0}'", friendlyName)
set GetVirtualSwitch= objWMIService.ExecQuery(query).ItemIndex(0)
End Function
'-----------------------------------------------------------------
' Retrieve VirtualSwitchPort
'-----------------------------------------------------------------
Function GetVirtualSwitchPort(switch, switchPortFriendlyName)
dim query, switchPort, switchPorts
set GetVirtualSwitchPort = Nothing
query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_SwitchPort", switch.Path_.Path)
set switchPorts= objWMIService.ExecQuery(query)
for each switchPort in switchPorts
if lcase(switchPort.ElementName) = lcase(switchPortFriendlyName) then
set GetVirtualSwitchPort = switchPort
end if
next
End Function
'-----------------------------------------------------------------
' Get VM Ethernet port
'-----------------------------------------------------------------
Function GetVMEthernetPort(vmName, vmEthernetPortClass)
dim query, vmEthernetPort, vm
set GetVMEthernetPort = Nothing
query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmName)
set vm= objWMIService.ExecQuery(query).ItemIndex(0)
if (vm Is Nothing) then
WriteLog Format1("Unable to find specified VM {0}", vmName)
WScript.Quit(1)
end if
query = Format2("ASSOCIATORS OF {{0}} WHERE resultClass = {1}", vm.Path_.Path, vmEthernetPortClass)
set GetVMEthernetPort = objWMIService.ExecQuery(query).itemIndex(0)
End Function
'-----------------------------------------------------------------
' Get VM Ethernet port endpoint
'-----------------------------------------------------------------
Function GetVMEthernetPortEndPoint(vmEthernetPort)
dim query, vmEthernetPorts, vm
set GetVMEthernetPortEndPoint = Nothing
query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_VmLANEndpoint", vmEthernetPort.Path_.Path)
set GetVMEthernetPortEndPoint = objWMIService.ExecQuery(query).ItemIndex(0)
End Function
'-----------------------------------------------------------------
' Connect switch port with vm Ethernet endpoint
'-----------------------------------------------------------------
Function ConnectSwitchPort(switchPort, lanEndpoint)
dim objInParam, objOutParams
ConnectSwitchPort = false
set objInParam = switchService.Methods_("ConnectSwitchPort").InParameters.SpawnInstance_()
objInParam.LANEndPoint = lanEndpoint.Path_.Path
objInParam.SwitchPort = switchPort.Path_.Path
set objOutParams = switchService.ExecMethod_("ConnectSwitchPort", objInParam)
if objOutParams.ReturnValue = wmiSuccessful then
ConnectSwitchPort = true
else
WriteLog Format1("ConnectSwitchPort failed with error code {0}", objOutParams.ReturnValue)
end if
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
dim fileStream
set fileStream = fileSystem.OpenTextFile(".\ConnectSwitchPort.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
Format2 = Format1(myString, arg0)
Format2 = Replace(Format2, "{1}", arg1)
End Function
'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
Format1 = Replace(myString, "{0}", arg0)
End Function
Requirements
| Minimum supported client |
None supported |
| Minimum supported server |
Windows Server 2008 |
| End of client support |
None supported |
| End of server support |
Windows Server 2012 |
| Namespace |
Root\Virtualization |
| MOF |
|