LucD notes

One of the feature requests that came up in several emails I received for my dvSwitch series, was how to get and set the network adapters of virtual guests. In the current PowerCLI version the Get-NetworkAdapter and Set-NetworkAdapter cmdlets can not handle portgroups on dvSwitches.

That is why I created the following two functions, called Get-dvSwNetworkAdapter and Set-dvSwNetworkAdapter.

The script

In the functions I tried to emulate the existing Get-NetworkAdapter and Set-NetworkAdapter cmdlets.

Update March 21st 2010

Mike Laverick reported some problems with the original functions when an array of objects was passed as an argument. I have rewritten both functions to handle parameter arrays correctly.

Update June 3rd 2010

Glenn Sizemore, winner of the 2010 Scripting Games, reworked the functions so that they now work with a standard vSwitch and a dvSwitch! See dvSwitchNetworkAdapter for Glenn’s code.

function Get-dvSwNetworkAdapter{
	param([parameter(Mandatory = $true, ValueFromPipeline = $true)][VMware.VimAutomation.Client20.VirtualMachineImpl[]]$VM
	)

	process{
		$VM | Get-View | %{
			$vmObj = $_
			$vmObj.Config.Hardware.Device | where {"VirtualEthernetCard","VirtualVmxnet" -contains $_.GetType().BaseType.Name} | %{
				$net = $_
				New-Object PSObject -Property @{
					MacAddress = $net.MacAddress
					WakeOnLanEnabled = $net.WakeOnLanEnabled
					NetworkName = &{
						if($net.Backing.GetType().Name -eq "VirtualEthernetCardNetworkBackingInfo"){
							(Get-View $_.Backing.network).Name
						}
						else{
							($vmObj.Network | %{Get-View $_} | where{$_.Key -eq $net.Backing.Port.PortgroupKey}).Name
						}
					}
					Type = $net.GetType().Name
					ParentId = $vmObj.MoRef.Type + "-" + $vmObj.MoRef.Value
					ConnectionState = New-Object PSObject -Property @{
						Connected = $net.Connectable.Connected
						StartConnected = $net.Connectable.StartConnected
					}
					Id = $vmObj.MoRef.Type + "-" + $vmObj.MoRef.Value + "/" + $net.Key
					Name = $net.DeviceInfo.Label
				}
			}
		}
	}
}

function Set-dvSwNetworkAdapter{
	param([parameter(Mandatory = $true, ValueFromPipeline = $true)][PSCustomObject[]]$NetworkAdapter,
	[parameter(Mandatory = $true)][string]$NetworkName,
	[switch]$StartConnected,
	[switch]$Connected
	)

	process{
		$NetworkAdapter | %{
			$netAdapter = $_
			$vm = Get-View $netAdapter.ParentId
			$esx = Get-View $vm.Runtime.Host
			$newNet = $esx.Network | %{Get-View $_} | where {$_.Name -eq $NetworkName}
			$spec = New-Object VMware.Vim.VirtualMachineConfigSpec

			$dev = New-Object VMware.Vim.VirtualDeviceConfigSpec
			$dev.operation = "edit"
			$dev.device = $vm.Config.Hardware.Device | where {$_.GetType().Name -eq $netAdapter.Type -and $_.MacAddress -eq $netAdapter.MacAddress}

			# Determine backing type
			switch($newNet.GetType().Name){
				"Network" {
					$dev.device.backing = New-Object VMware.Vim.VirtualEthernetCardNetworkBackingInfo
					$dev.device.backing.deviceName = $NetworkName
				}
				"DistributedVirtualPortgroup" {
					$dev.device.Backing = New-Object VMware.Vim.VirtualEthernetCardDistributedVirtualPortBackingInfo
					$dev.device.backing.port = New-Object VMware.Vim.DistributedVirtualSwitchPortConnection

					$dev.device.backing.port.switchUuid = (Get-View $newNet.Config.DistributedVirtualSwitch).Uuid
					$dev.device.backing.port.portgroupKey = $newNet.Config.Key
				}
			}
			if($Connected -ne $null){
				$dev.Device.Connectable.Connected = $Connected
			}
			if($StartConnected -ne $null){
				$dev.Device.Connectable.StartConnected = $StartConnected
			}
			$spec.deviceChange += $dev
			$taskMoRef = $vm.ReconfigVM_Task($spec)

			$task = Get-View $taskMoRef
			while("running","queued" -contains $task.Info.State){
				$task.UpdateViewData("Info")
			}
			$returnNetworkAdapter = $netAdapter
			$returnNetworkAdapter.NetworkName = $NetworkName
			$returnNetworkAdapter.ConnectionState.StartConnected = $dev.Device.Connectable.StartConnected
			$returnNetworkAdapter.ConnectionState.Connected = $dev.Device.Connectable.Connected
			$returnNetworkAdapter
		}
	}
}

Annotations

Line 2: The Get-dvSwNetworkAdapter function requires a single parameter, the virtual machine for which you want to get the network adapter information.

Line 5: With the Process block the function can act as a filter. In other words, the function can be used in a pipeline construct.

Line 6: This loop takes care if the VM parameter is an array.

Line 8: The Where-Object filter only allows virtual devices that have the basetype VirtualEthernetCard or VirtualVmxnet to enter the script block that follows. By using the basetype the script doesn’t have to test all the derived objects.

Line 10: The returned information will be in a PSObject. The PSObject has the same properties that are present in the NetworkAdapterImpl that is returned by the Get-NetworkAdapter cmdlet.

Line 13-19: The network name has to be retrieved from different properties depending on the fact if the card is connected to vSwitch portgroup or to a dvSwitch portgroup.

Line 23-26: The ConnectionState property, which is a ConnectInfo object with the Get-NetworkAdapter cmdlet, contains a PSObject. But the property names and the values are the same.

Line 27: The Id property is constructed from the Id of the virtual machine and the device key of the network card. This is the same as what the Get-NetworkAdapter cmdlet returns.

Line 36-37: The Set-dvSwNetworkAdapter function has two required parameters. A network adapter object, as is returned by the Get-dvSwNetworkAdapter cmdlet, and the name of the portgroup to which the adapter shall be connected. Notice that the NetworkAdapter parameter can be passed via the pipeline.

Line 38-39: The function has two optional switch parameters, StartConnected and Connected.

Line 41: With the Process block the function can act as a filter. In other words, the function can be used in a pipeline construct.

Line 43: This loop takes care if the NetworkAdapter parameter is an array.

Line 47: This construct looks up the new portgroup to which the network adapter will be connected.

Line 48-67: These lines prepare the parameters for the ReconfigVM_Task method that is used to change the portgroup to which the network card is connected.

Line 52: The script copies the VirtualDevice object into the VirtualMachineConfigSpec object. This action minimises the data that will have to be entered into the properties. On March 26th 2010 I have added the condition that the MAC address should correspond as well. Otherwise there could eventually be multiple NICs that fit the condition. Rich, thanks for the discovery and the correction.

Line 55: Depending if the new portgroup is on a vSwitch or on a dvSwitch, the Backing property of the VirtualDevice is of a different type.

Line 68-73: These lines take care of the StartConnected and Connected switches.

Line 78-80: This is the “standard” loop to wait for the completion of a Task method.

Line 85: The function returns the new network adapter information through a PSObject. Similar to what the Get-dvSwNetworkAdapter function does.

Usage

Some sample use cases of the two functions.

Getting adapter information

Similar to the Get-NetworkAdapter cmdlet you can retrieve information from the network adapter(s).

$vmName = "MyGuest"

Get-dvSwNetworkAdapter -VM (Get-VM $vmName)

Returns something like this

Changing the adapters

To change the portgroup of a network adapter you can use something like this

$vmName = "MyGuest"

Get-dvSwNetworkAdapter -VM (Get-VM $vmName) | where {$_.NetworkName -eq "Net2"} | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"

And the changed network adapter will be returned.

The functions can handle calls of the following formats

Get-VM -Name "MyVm1" | get-dvSwNetworkAdapter | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-VM -Name "MyVm*" | get-dvSwNetworkAdapter | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-dvSwNetworkAdapter -VM (Get-VM MyVm1) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-dvSwNetworkAdapter -VM (Get-VM MyVm*) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-dvSwNetworkAdapter (Get-VM MyVm) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-dvSwNetworkAdapter (Get-VM MyVm*) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2"
Get-dvSwNetworkAdapter (Get-VM MyVm*) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2" -StartConnected:$true
Get-dvSwNetworkAdapter -VM (Get-VM MyVm1) | Set-dvSwNetworkAdapter -NetworkName "dvPgNet2" -Connected:$true -StartConnected:$true

Conclusion

I hope these two functions come in handy in your work with dvSwitches.

And a word of warning, the two functions don’t perform any error checking whatsoever. If you pass no network adapter object to the Set-dvSwNetworkAdapter function, it will fail ! Same if you pass the name of a non-existing portgroup name.