Binds an external Ethernet port to the Microsoft Windows Virtualization network subsystem. After this call is
made, virtual machines can use the external Ethernet port to send data out over the physical network.
Syntax
uint32 BindExternalEthernetPort(
[in] Msvm_ExternalEthernetPort REF ExternalEthernetPort
);
Parameters
- ExternalEthernetPort [in]
-
A reference to the external Ethernet port to be bound. See
Msvm_ExternalEthernetPort.
Return Value
The method returns 0 if it succeeded synchronously. Any other return value indicates an error.
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 binds an external Ethernet port. The referenced utilities can be found in
Common Utilities for the Virtualization Samples.
using System;
using System.Management;
namespace HyperVSamples
{
class BindExternalEthernetPortClass
{
static void BindExternalEthernetPort(string externalEthernetPortName)
{
ManagementScope scope = new ManagementScope(@"root\virtualization", null);
ManagementObject switchService = Utility.GetServiceObject(scope, "Msvm_VirtualSwitchManagementService");
ManagementObject externalEthernetPort = Utility.GetHostSystemDevice("Msvm_msvm_ExternalEthernetPort", externalEthernetPortName, scope);
ManagementBaseObject inParams = switchService.GetMethodParameters("BindExternalEthernetPort");
inParams["ExternalEthernetPort"] = externalEthernetPort.Path.Path;
ManagementBaseObject outParams = switchService.InvokeMethod("BindExternalEthernetPort", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("{0} was bound successfully", externalEthernetPort["Name"]);
}
else
{
Console.WriteLine("Failed to bind {0} external Ethernet port.", externalEthernetPort["Name"]);
}
}
static void Main(string[] args)
{
if (args != null && args.Length != 2)
{
Console.WriteLine("Usage:\nBindExternalEthernetPort ExternalEthternetPortFriendlyName");
Console.WriteLine("Example:\nBindExternalEthernetPort \"Intel(R) PRO/1000 PM Network Connection\"");
return;
}
BindExternalEthernetPort(args[0]);
}
}
}
The following VBScript sample binds an external Ethernet port.
option explicit
dim objWMIService
dim switchService
dim fileSystem
const wmiSuccessful = 0
Main()
'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
dim computer, objArgs, externalEthernetPort, firendlyName
set objArgs = WScript.Arguments
if WScript.Arguments.Count = 1 then
firendlyName = objArgs.Unnamed.Item(0)
else
WScript.Echo "usage: cscript BindExternalEthernetPort ExternalEthternetPortFriendlyName"
WScript.Echo "Example: BindExternalEthernetPort ""Intel(R) PRO/1000 PM Network Connection"""
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 externalEthernetPort = GetExternalEthernetPort(firendlyName)
if (externalEthernetPort Is Nothing) then
WriteLog Format1("Unable to find external Ethernet Port {0}", firendlyName)
WScript.Quit(1)
end if
if BindExternalEthernetPort(externalEthernetPort) then
WriteLog "Done"
WScript.Quit(0)
else
WriteLog("BindExternalEthernetPort failed")
WScript.Quit(1)
end if
End Sub
'-----------------------------------------------------------------
' 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
'-----------------------------------------------------------------
' Bind the External Ethernet Port by calling BindExternalEthernetPort
'-----------------------------------------------------------------
Function BindExternalEthernetPort(externalEthernetPort)
dim objInParam, objOutParams
BindExternalEthernetPort = false
set objInParam = switchService.Methods_("BindExternalEthernetPort").InParameters.SpawnInstance_()
objInParam.ExternalEthernetPort = externalEthernetPort.Path_.Path
set objOutParams = switchService.ExecMethod_("BindExternalEthernetPort", objInParam)
if objOutParams.ReturnValue = wmiSuccessful then
BindExternalEthernetPort = true
else
WriteLog Format1("BindExternalEthernetPort 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(".\BindExternalEthernetPort.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formating 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 |
| MOF | WindowsVirtualization.mof |
| Namespace | \\.\Root\Virtualization |
See Also
- Msvm_VirtualSwitchManagementService
Send comments about this topic to Microsoft
Build date: 10/8/2009