SetupSwitch method of the Msvm_VirtualSwitchManagementService class

Sets up a switch such that the existing network architecture is maintained.

Syntax

uint32 SetupSwitch(
  [in]  Msvm_SwitchPort           REF ExternalSwitchPort,
  [in]  Msvm_SwitchPort           REF InternalSwitchPort,
  [in]  Msvm_ExternalEthernetPort REF ExternalEthernetPort,
  [in]  string                        InternalEthernetPortName,
  [in]  string                        InternalEthernetPortFriendlyName,
  [out] Msvm_NetworkJob           REF Job
);

Parameters

ExternalSwitchPort [in]

Type: Msvm_SwitchPort

The switch port to which the external Ethernet port is to be connected. See Msvm_SwitchPort.

InternalSwitchPort [in]

Type: Msvm_SwitchPort

The switch port to which the internal Ethernet port is to be connected.

ExternalEthernetPort [in]

Type: Msvm_ExternalEthernetPort

A reference to the external Ethernet port that is to be bound. See Msvm_ExternalEthernetPort.

InternalEthernetPortName [in]

Type: string

The name of the internal Ethernet port. This name must be unique among Ethernet ports.

InternalEthernetPortFriendlyName [in]

Type: string

A user-readable name for the internal Ethernet port.

Job [out]

Type: Msvm_NetworkJob

The work for setting up the switch is always an asynchronous background task because of the possibility of a network disconnection. This job reference can be used to find the result after and during the task. See Msvm_NetworkJob.

Return value

Type: uint32

If this method returns 4096, then the method is being executed asynchronously, and the Job output parameter may be used to track the progress of the asynchronous operation. 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 sets up a switch. The referenced utilities can be found in Common Utilities for the Virtualization Samples.

using System;
using System.Management;

namespace HyperVSamples
{
    class SetupSwitchClass
    {
        ManagementObject switchService = null;
        ManagementScope scope = null;

        SetupSwitchClass()
        {
            scope = new ManagementScope(@"root\virtualization", null);
            switchService = Utility.GetServiceObject(scope, "Msvm_VirtualSwitchManagementService");
        }

        ManagementObject GetExternalEthernetPort(string externalEthernetPortName)
        {
            ManagementObject externalEthernetPort = Utility.GetHostSystemDevice("Msvm_ExternalEthernetPort", externalEthernetPortName, scope);
            return externalEthernetPort;
        }

        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() == switchPortName)
                {
                    switchPort = instance;
                    break;
                }
            }

            return switchPort;
        }

        ManagementObject CreateSwitchPort(string friendlyName, string name, ManagementObject virtualSwitch)
        {

            ManagementObject createdSwitchPort = null;

            ManagementBaseObject inParams = switchService.GetMethodParameters("CreateSwitchPort");

            inParams["FriendlyName"] = friendlyName;
            inParams["Name"] = name;
            inParams["VirtualSwitch"] = virtualSwitch.Path.Path;
            inParams["ScopeofResidence"] = null;
            ManagementBaseObject outParams = switchService.InvokeMethod("CreateSwitchPort", inParams, null);
            if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
            {
                createdSwitchPort = new ManagementObject(outParams["CreatedSwitchPort"].ToString());
                Console.WriteLine("{0} is created successfully", inParams["Name"]);
            }
            else
            {
                Console.WriteLine("Failed to create {0} switch port.", inParams["Name"]);
            }

            inParams.Dispose();
            outParams.Dispose();

            return createdSwitchPort;
        }


        void SetupSwitch
        (
            ManagementObject externalSwitchPort,
            ManagementObject internalSwitchPort,
            ManagementObject externalEthernetPort,
            string internalEthernetPortName,
            string internalEthernetPortFriendlyName

            )
        {
            ManagementBaseObject inParams = switchService.GetMethodParameters("SetupSwitch");
            inParams["InternalSwitchPort"] = internalSwitchPort.Path.Path;
            inParams["ExternalSwitchPort"] = externalSwitchPort.Path.Path;
            inParams["ExternalEthernetPort"] = externalEthernetPort.Path.Path;
            inParams["internalEthernetPortName"] = internalEthernetPortName;
            inParams["InternalEthernetPortFriendlyName"] = internalEthernetPortFriendlyName;

            ManagementBaseObject outParams = switchService.InvokeMethod("SetupSwitch", inParams, null);

            if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
            {
                if (Utility.JobCompleted(outParams, scope))
                {
                    Console.WriteLine("SetupSwitch passed.");
                }
                else
                {
                    Console.WriteLine("SetupSwitch failed.");
                }
            }
            else if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
            {
                Console.WriteLine("SetupSwitch passed.");
            }
            else
            {
                Console.WriteLine("SetupSwitch failed.");
            }

            inParams.Dispose();
            outParams.Dispose();
        }

        void Close()
        {
            this.switchService.Dispose();
        }

        static void Main(string[] args)
        {
            if (args != null && args.Length != 6)
            {
                Console.WriteLine("Usage:\nSetupSwitch switchName internalSwitchPortFriendlyName");
                Console.WriteLine("       externalSwitchPortFriendlyName externalEthernetPortFriendlyName");
                Console.WriteLine("       internalEthernetPortName internalEthernetPortFriendlyName");
                Console.WriteLine("Example:\nSetupSwitch {0} {1} {2} {3} {4} {5} {6} \"{7}\"",
                    "FirstSwitch",
                    "MyInternalSwitchPort",
                    "MyExternalSwitchPort",
                    "Intel(R) PRO/1000 PM Network Connection",
                    "InternalEthernetPortName",
                    "MyInternalEthernetPortName"
                    );
                return;
            }
            string switchName = args[0];
            string internalSwitchPortFriendlyName = args[1];
            string externalSwitchPortFriendlyName = args[2];
            string externalEthernetPortFriendlyName = args[3];
            string internalEthernetPortName = args[4];
            string internalEthernetPortFriendlyName = args[5];
            SetupSwitchClass setupSwitchClass = new SetupSwitchClass();
            ManagementObject virtualSwitch = setupSwitchClass.GetVirtualSwitch(switchName);
            if (virtualSwitch == null)
            {
                Console.WriteLine("Unable to find virtual switch '{0}'}", switchName);
                return;
            }

            ManagementObject internetSwitchPort = setupSwitchClass.GetVirtualSwitchPort(virtualSwitch, internalSwitchPortFriendlyName);
            if (internetSwitchPort == null)
            {
                Console.WriteLine("Unable to find switch port '{0}'}", internalSwitchPortFriendlyName);
            }

            ManagementObject externalSwitchPort = setupSwitchClass.GetVirtualSwitchPort(virtualSwitch, externalSwitchPortFriendlyName);
            if (internetSwitchPort == null)
            {
                Console.WriteLine("Unable to find switch port '{0}'}", externalSwitchPortFriendlyName);
            }

            ManagementObject externalEthernetPort = setupSwitchClass.GetExternalEthernetPort(externalEthernetPortFriendlyName);

            if (externalEthernetPort == null)
            {
                Console.WriteLine("Unable to find external Ethernet port'{0}'}", externalEthernetPortFriendlyName);
            }

            setupSwitchClass.SetupSwitch
            (
                externalSwitchPort,
                internetSwitchPort,
                externalEthernetPort,
                internalEthernetPortName,
                internalEthernetPortFriendlyName
            );

            externalSwitchPort.Dispose();
            internetSwitchPort.Dispose();
            externalEthernetPort.Dispose();
            virtualSwitch.Dispose();

            setupSwitchClass.Close();

        }
    }
}

The following VBScript sample sets up a switch.

option explicit 

dim objWMIService
dim switchService
dim fileSystem

const JobStarting = 3
const JobRunning = 4
const JobCompleted = 7
const wmiStarted = 4096
const wmiSuccessful = 0

Main()

'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
    dim computer, objArgs 
    dim switchFriendlyName, internalSwitchPortFriendlyName
    dim externalSwitchPortFriendlyName, externalEthernetPortFriendlyName
    dim internalEthernetPortName, internalEthernetPortFriendlyName
    dim switch, internalSwitchPort, externalSwitchPort, externalEthernetPort

    set objArgs = WScript.Arguments
    if WScript.Arguments.Count = 6 then
       switchFriendlyName = objArgs.Unnamed.Item(0)
       internalSwitchPortFriendlyName = objArgs.Unnamed.Item(1)
       externalSwitchPortFriendlyName = objArgs.Unnamed.Item(2)
       externalEthernetPortFriendlyName = objArgs.Unnamed.Item(3)
       internalEthernetPortName = objArgs.Unnamed.Item(4)
       internalEthernetPortFriendlyName = objArgs.Unnamed.Item(5)
    else
       WScript.Echo "usage: cscript SetupSwitch " &_
                            "switchName " &_
                            "internalSwitchPortFriendlyName " &_
                            "externalSwitchPortFriendlyName " &_
                            "externalEthernetPortFriendlyName " &_
                            "internalEthernetPortName " &_
                            "internalEthernetPortFriendlyName"
       WScript.Echo "Example: SetupSwitch " &_
                              "FirstSwitch " &_
                              "MyInternalSwitchPort " &_
                              "MyExternalSwitchPort " &_
                              """Intel(R) PRO/1000 PM Network Connection"" " &_
                              "InternalEthernetPortName " &_
                              "MyInternalEthernetPortName "
       WScript.Quit(1)
    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 internalSwitchPort = GetVirtualSwitchPort(switch, internalSwitchPortFriendlyName)
    if (internalSwitchPort Is Nothing) then
        WriteLog Format1("Unable to find switchPort '{0}'.", internalSwitchPortFriendlyName)
        WScript.Quit(1)   
    end if 
    
    
    set externalSwitchPort = GetVirtualSwitchPort(switch, externalSwitchPortFriendlyName)
    if (externalSwitchPort Is Nothing) then
        WriteLog Format1("Unable to find switchPort '{0}'.", externalSwitchPortFriendlyName)
        WScript.Quit(1)   
    end if 
        
    set externalEthernetPort = GetExternalEthernetPort(externalEthernetPortFriendlyName)
    if (externalEthernetPort Is Nothing) then
       WriteLog Format1("Unable to find external Ethernet Port {0}", externalEthernetPortFriendlyName)
       WScript.Quit(1)
    end if    
    
    if SetupSwitch( _
        externalSwitchPort, _
        internalSwitchPort, _
        externalEthernetPort, _ 
        internalEthernetPortName, _ 
        internalEthernetPortFriendlyName _
        ) _
    then
        WriteLog "Done"
        WScript.Quit(0)
    else
        WriteLog "SetupSwitch failed"
        WScript.Quit(1)
    end if

End Sub

'-----------------------------------------------------------------
' 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

'-----------------------------------------------------------------
' Retrieve the external Ethernet port 
'-----------------------------------------------------------------
Function GetExternalEthernetPort(externalEthernetPortFriendlyName)
    dim objNTInfo, computerName, query, computer
    dim externalEthernetPort, externalEthernetPorts
    
    set GetExternalEthernetPort = Nothing
    set objNTInfo = CreateObject("WinNTSystemInfo")
    computerName = lcase(objNTInfo.ComputerName)

    query = Format1("select * from Msvm_ComputerSystem where Name = '{0}'", computerName)
    set computer = objWMIService.ExecQuery(query).ItemIndex(0)
    
    query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_ExternalEthernetPort", computer.Path_.Path)
    set externalEthernetPorts = objWMIService.ExecQuery(query)
    for each externalEthernetPort in externalEthernetPorts
        if lcase(externalEthernetPort.ElementName) = lcase(externalEthernetPortFriendlyName) then
            set GetExternalEthernetPort = externalEthernetPort
            Exit Function
        end if
    next
End Function

'-----------------------------------------------------------------
' setup a virtual switch by calling SetupSwitch WMI method
'-----------------------------------------------------------------
Function SetupSwitch( _
    externalSwitchPort, _
    internalSwitchPort, _
    externalEthernetPort, _ 
    internalEthernetPortName, _ 
    internalEthernetPortFriendlyName _
) 
    dim objInParam, objOutParams
    
    SetupSwitch = false
    set objInParam = switchService.Methods_("SetupSwitch").InParameters.SpawnInstance_()

    objInParam.ExternalSwitchPort = externalSwitchPort.Path_.Path
    objInParam.InternalSwitchPort = internalSwitchPort.Path_.Path
    objInParam.ExternalEthernetPort = externalEthernetPort.Path_.Path
    objInParam.InternalEthernetPortName = internalEthernetPortName
    objInParam.InternalEthernetPortFriendlyName = internalEthernetPortFriendlyName

    set objOutParams = switchService.ExecMethod_("SetupSwitch", objInParam)

    if objOutParams.ReturnValue = wmiStarted then
        if (WMIJobCompleted(objOutParams)) then
            SetupSwitch = true
        end if
    elseif (objOutParams.ReturnValue = wmiSuccessful) then
        SetupSwitch = true
    else
        WriteLog Format1("SetupSwitch failed with error {0}", objOutParams.ReturnValue)
    end if
End Function

'-----------------------------------------------------------------
' Handle wmi Job object
'-----------------------------------------------------------------
Function WMIJobCompleted(outParam)
    
    dim WMIJob, jobState
    WMIJobCompleted = true

    set WMIJob = objWMIService.Get(outParam.Job)
    
    jobState = WMIJob.JobState

    while jobState = JobRunning or jobState = JobStarting
        WriteLog Format1("In progress... {0}% completed.",WMIJob.PercentComplete)
        WScript.Sleep(1000)
        set WMIJob = objWMIService.Get(outParam.Job)
        jobState = WMIJob.JobState
    wend

    if (WMIJob.JobState <> JobCompleted) then
        WriteLog Format1("ErrorDescription:{0}", WMIJob.ErrorDescription)
        WriteLog Format1("ErrorCode:{0}", WMIJob.ErrorCode)
        WMIJobCompleted = false
    end if
    
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
    dim fileStream
    set fileStream = fileSystem.OpenTextFile(".\SetupSwitch.log", 8, true)
    WScript.Echo line
    fileStream.WriteLine line
    fileStream.Close

End Sub

'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
    if IsNull(arg0) then
        Format1 = Replace(myString, "{0}", "NULL")
    else
        Format1 = Replace(myString, "{0}", arg0)
    end if
End Function

Requirements

See also

Msvm_VirtualSwitchManagementService