CreateSwitch method of the Msvm_VirtualSwitchManagementService class

Creates a new virtual switch.

Syntax

uint32 CreateSwitch(
  [in]  string                 Name,
  [in]  string                 FriendlyName,
  [in]  uint32                 NumLearnableAddresses,
  [in]  string                 ScopeOfResidence,
  [out] Msvm_VirtualSwitch REF CreatedVirtualSwitch
);

Parameters

Name [in]

Type: string

The name of the switch. This name must be unique to all virtual switches in the system.

FriendlyName [in]

Type: string

A user-readable name for the switch.

NumLearnableAddresses [in]

Type: uint32

The maximum number of MAC addresses that can be learned by the switch.

ScopeOfResidence [in]

Type: string

The initial scope of the switch.

CreatedVirtualSwitch [out]

Type: Msvm_VirtualSwitch

Upon successful completion of this method, this parameter contains the created switch. See Msvm_VirtualSwitch.

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 creates a virtual switch. The referenced utilities can be found in Common Utilities for the Virtualization Samples.

using System;
using System.Management;

namespace HyperVSamples
{
    class CreateSwitchClass
    {
        static ManagementObject CreateSwitch(string name, string friendlyName, int learnableAddress)
        {
            ManagementScope scope = new ManagementScope(@"root\virtualization", null);
            ManagementObject switchService = Utility.GetServiceObject(scope, "Msvm_VirtualSwitchManagementService");

            ManagementObject createdSwitch = null;

            ManagementBaseObject inParams = switchService.GetMethodParameters("CreateSwitch");
            inParams["FriendlyName"] = friendlyName;
            inParams["Name"] = name;
            inParams["NumLearnableAddresses"] = learnableAddress;
            inParams["ScopeofResidence"] = null;
            ManagementBaseObject outParams = switchService.InvokeMethod("CreateSwitch", inParams, null);
            if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
            {
                Console.WriteLine("{0} was created successfully", inParams["Name"]);
                createdSwitch = new ManagementObject(outParams["CreatedVirtualSwitch"].ToString());
            }
            else
            {
                Console.WriteLine("Failed to create {0} switch.", inParams["Name"]);
            }
            return createdSwitch;
        }

        static void Main(string[] args)
        {
            if (args != null && args.Length != 3)
            {
                Console.WriteLine("Usage: CreateSwitch name friendlyName NumLearnableAddresses");
                Console.WriteLine("Example: CreateSwitch FirstSwitch \"My First Switch\" 1024");
                return;
            }
            CreateSwitch(args[0], args[1], int.Parse(args[2]));
        }
    }
}

The following VBScript sample creates a virtual switch.

option explicit 

dim objWMIService
dim switchService
dim fileSystem

const wmiStarted = 4096
const wmiSuccessful = 0

Main()

'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()

    dim name, friendlyName, learnableAddress
    dim computer, objArgs, createdSwitch

    set objArgs = WScript.Arguments
    if WScript.Arguments.Count = 3 then
       name = objArgs.Unnamed.Item(0)
       friendlyName = objArgs.Unnamed.Item(1)
       learnableAddress = objArgs.Unnamed.Item(2)
    else
       WScript.Echo "usage: cscript CreateSwitch.vbs name friendlyName learnableAddress"
       WScript.Echo "Example: CreateSwitch FirstSwitch ""My First Switch"" 1024"
       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 createdSwitch = CreateSwitch(name, friendlyName, learnableAddress)
    
    if createdSwitch Is Nothing then
        WriteLog "CreateSwitch failed."
        WScript.Quit(1)
    else
        WriteLog "Done"
        WScript.Quit(0)
    end if

End Sub

'-----------------------------------------------------------------
' Create a virtual switch by calling CreateSwitch WMI method
'-----------------------------------------------------------------
Function CreateSwitch(name, friendlyName, learnableAddress)

    dim objInParam, objOutParams
    
    set CreateSwitch = Nothing
    set objInParam = switchService.Methods_("CreateSwitch").InParameters.SpawnInstance_()
    objInParam.FriendlyName = friendlyName
    objInParam.Name = name
    objInParam.NumLearnableAddresses = learnableAddress
    objInParam.ScopeofResidence = null

    set objOutParams = switchService.ExecMethod_("CreateSwitch", objInParam)
    
    if objOutParams.ReturnValue = wmiSuccessful then
        set CreateSwitch = objWMIService.Get(objOutParams.CreatedVirtualSwitch)
    else
        WriteLog Format1("CreateSwitch 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(".\CreateSwitch.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)
    Format1 = Replace(myString, "{0}", arg0)
End Function

Requirements

See also

Msvm_VirtualSwitchManagementService

Msvm_VirtualSwitch