Home > Blogs > VMware PowerCLI Blog > Author Archives: Vitali Baruh

Author Archives: Vitali Baruh

Ability to customize VI objects



New-VIProperty is commandlet that gives the ability to
customize all VI objects and make them more informative. For example it is
possible to add a property “OverallStatus” to each inventory object /VM host, virtual
machine, resource pool, cluster, etc./ that shows the overall status of the
concrete inventory item – green, gray, etc.

Let see how it works – first a new property is created using
the commandlet New-VIProperty. Afterward using the Get-Inventory commandlet retreive
the name and the overall status of all inventory items.

PS> New-VIProperty -ObjectType InventoryItem -Name
OverallStatus -ValueFromExtensionProperty ‘OverallStatus’


PS> Get-Inventory | select Name,OverallStatus |
Format-Table -AutoSize

Name                              OverallStatus

—-                              ————-

WinXP-1                                   green

WinXP-2                                   green

WinXP-3                                   green

WinXP-4                                   green

Cluster-1                                 green

Cluster-1                                 green

Cluster-1                                 green

…                                         …

…                                         …

…                                         …


Where does come from the information
about the overall status?

The VI SDK has a type that represents each infrastructure
object. PowerCLI works with objects that contain some subset of properties of
the corresponding SDK object. PowerCLI does not represent the whole SDK object
because its retrieval is time consuming operation and it would not be

PowerCLI gives the ability to obtain the full SDK objects by
the commandlet Get-View. Get-View commandlet returns vSphere .Net view objects.

Another way to retrieve a .Net View
representation of given PowerCLI object, is to refer to its

The ExtensionData property is “on-demand” property. This
means that the value of the property is initialized on the first referral to
it. This approach is used again because of the slow retrieval of the whole .Net
view object.

New-VIProperty commandlet gives the ability to define custom
property to VI types. These properties can refer directly property of the .Net
view object or can be powershell script block which evaluates to some value.

Each instance of the customized type or instance of
its inheritor types will has the customized property.

All customized properties are available during the
life of the powershell process or until they are removed using
Remove-VIProperty commandlet.

Type of custom properties


There are two types of custom properties – script properties
and properties based on extension data property.

Properties based on extension data

Property of this type refers directly property of the .Net
view object.

Creating custom properties on virtual machine type:

ToolsStatus – shows status of the VM Tools

ToolsVersion – shows version of the VM Tools

PS> New-VIProperty -ObjectType VirtualMachine -Name
ToolsStatus -ValueFromExtensionProperty ‘Guest.ToolsStatus’

PS> New-VIProperty -ObjectType VirtualMachine -Name
ToolsVersion -ValueFromExtensionProperty ‘Guest.ToolsVersion’


PS> Get-VM | Select Name,ToolsStatus,ToolsVersion

Name                                    ToolsStatus

—-                                    ———–

Env3-VC4u1-2-yavor                          toolsOk 8193

Env5-VC4-1-vbaruh                           toolsOk 8193

Env3-VC4.1KL.Next-1                         toolsOk 8193

TestMachin2003-32bit-CS             toolsNotRunning

testMachine_Ubuntu                          toolsOk 8193

KLNext-VisorEnv-VC2                         toolsOk 8193

Env3-VC4-1                                  toolsOk 8193

VC20_TM22-Win2003                   toolsNotRunning 8193

PS20_win2003                        toolsNotRunning

testMachine_2003_32bit                      toolsOk 8193

VC4.0                               toolsNotRunning 8193

TestRunner-Win7-64bit                       toolsOk 8193

TestRunner-Win2003_64bit                    toolsOk 8193

TestRunner-WinXP-SP3-32bit                  toolsOk 8193

Env4-VC41-VC1                               toolsOk 8193

testMachine_Vista_32bit             toolsNotRunning

…                                             …   …

…                                             …   …

…                                             …   …


The value passed to the parameter ValueFromExtensionProperty
is path to the sub-property of the .Net view object. In this example two
properties are created that refer properties from the virtual machine .Net view

New-VIProperty performs verification for existence of
the referred .Net view property. If it does not exist the commandlet will write
an error.

For example creation of property that refers
“Guest.ToolsStatus” on type “Cluster” will throw an error. See:

PS> New-VIProperty -ObjectType Cluster -Name ToolsStatus
-ValueFromExtensionProperty ‘Guest.ToolsStatus’

New-VIProperty : 04.5.2010 г. 21:00:17    New-VIProperty       
Could not validate the specified path ‘Guest.ToolsStatus’ for any of the
following types

 (or their inheritors): ‘ClusterComputeResource’.


Creation of properties to ancestor types


Because SDK objects are hierarchal related it is possible to
define custom property on ancestor type and all its inheritors will have the
property too. In the following example the customized type is InventoryItem.
InventoryItem represents ManagedEntity SDK type. SDK types like VirtualMachine,
HostSystem,Folder, Datacenter inherit ManagedEntity, so they have all
properties defined in ManagedEntity.

Because of that it is possible to define property that
refers “OverallStatus” to InventoryItem and this property will appear in all
PowerCLI objects that inherits InventoryItem. Such types are VirtualMachine,
VMHost, Datacenter, Folder, Cluster, etc.

PS> New-VIProperty -ObjectType InventoryItem -Name
OverallStatus -ValueFromExtensionProperty ‘OverallStatus’



Creating of properties that point to array fields

.Net view objects have properties of array type. It is
possible to create customize field that points to such array fields. In that
case the custom property is an array too. In this example the custom property
points to all virtual machine files.

PS> New-VIProperty -ObjectType VirtualMachine -Name
FileList -ValueFromExtensionProperty ‘LayoutEx.File’

PS> $vm = Get-VM TestMachin2003-32bit-CS

PS> $vm.FileList


Key             : 0

Name            : [storage_114_58]

Type            : diskDescriptor

Size            : 537

DynamicType     :

DynamicProperty :

Key             : 1

Name            : [storage_114_58]

Type            : diskExtent

Size            : 8477736960

DynamicType     :

DynamicProperty :

Key             : 2

Name            : [storage_114_58]

Type            : diskDescriptor

Size            : 327

DynamicType     :

DynamicProperty :



It is also possible to create property that points to
sub-field of array field. For example it is possible to create property that
will hold only file names of the virtual machine files instead of holding the
whole information for each file.

PS> New-VIProperty -ObjectType VirtualMachine -Name
FileNameList -ValueFromExtensionProperty ‘LayoutEx.File.Name’

PS> $vm = Get-VM TestMachin2003-32bit-CS

PS> $vm.FileNameList






Using aggregate function on array properties

New-VIProperty can create property that is aggregation on
array values or sub-properties of array values. For example it is possible to
create property that gives the sum of size of all virtual machine files.

PS>  New-VIProperty -ObjectType VirtualMachine -Name
TotalFileSize -ValueFromExtensionProperty ‘SUM LayoutEx.File.Size’

PS> $vm = Get-VM TestMachin2003-32bit-CS

PS> $vm.TotalFileSize



In this example at the beginning of the property path
definition is defined the function that should be applied. Possible functions

Similarly it is possible to define properties that shows the
size of the smallest file, of the largest file and the average file size.

PS> New-VIProperty -ObjectType VirtualMachine -Name
MaxFileSize -ValueFromExtensionProperty ‘MAX LayoutEx.File.Size’

PS> New-VIProperty -ObjectType VirtualMachine -Name
MinFileSize -ValueFromExtensionProperty ‘MIN LayoutEx.File.Size’

PS> New-VIProperty -ObjectType VirtualMachine -Name
AvgFileSize -ValueFromExtensionProperty ‘AVG LayoutEx.File.Size’


PS> $vm | select
TotalFileSize,MaxFileSize,MinFileSize,AvgFileSize | Format-Table -AutoSize

TotalFileSize MaxFileSize MinFileSize     AvgFileSize

————- ———– ———–     ———–

   8478325916  8477736960           0 403729805.52381


Script properties


Script properties are defined by name and script that will
evaluate on the first retrieving of the property.

Properties that refers persistent properties of the target object

The simplest example is property that refers to one or more
properties of the customized type. This example creates a property that
evaluates to the name of the VM Host in which the virtual machine resides.

PS> New-VIProperty –Name NameOfHost –ObjectType
VirtualMachine –Value { return $args[0].VMHost.Name }


PS> get-VM | select Name,NameOfHost | Format-Table

Name                              NameOfHost

—-                              ———-










…                                 …

…                                 …

…                                 …


How should be the script block structured?

When vSphere PowerCLI commandlet see that it should evaluate
script property for given instance it passes that instances as parameter to the
script block. Because of that the object can be referenced as $args[0] inside
the script block.

It is possible to give name of the first parameter using the
Powershell key word param. See the above example written in
better way:

PS> New-VIProperty –Name NameOfHost –ObjectType
VirtualMachine –Value { param ($vm) return $vm.VMHost.Name }


Here the first parameter is named as $vm and this name is
used inside the whole script block.

Script-based properties that refers values from extension data


As it shown in the above example, inside the script block,
it is possible to work with each property of the customized type. This mean
that it is possible to work with the new property ExtensionData. As it was
mention above the retrieving of the whole ExtensionData is slow operation. This
slow initialization can be easily observed in the following example.

PS> New-VIProperty -Name ToolsStatus -ObjectType VirtualMachine
-Value { param ($vm) return $vm.ExtensionData.Guest.ToolsStatus; }

PS> Get-VM | select Name,ToolsStatus

…   … …


After calling the above command it can be observed that
there is some delay before each new row is displayed. This delay is caused by
the whole retrieval of the ExtensionData object.

To avoid this slow initialization New-VIProperty gives an
option to specify which properties from the ExtensionData to be retrieved. In
this way only the needed portion of the .Net view object will be retrieved and
the delay will be smaller.

This mechanism is called “hinting”.

PS> New-VIProperty -Name ToolsStatus -ObjectType
VirtualMachine -Value { param ($vm) return $vm.ExtensionData.Guest.ToolsStatus;
} -BasedOnExtensionProperty ‘Guest.ToolsStatus’


PS> Get-VM | Select Name,ToolsStatus


This time the above call will finish without any obvious
delay. This is that because during this call only the “Guest.ToolsStatus” is
retrieved from the ExtensionData property.

This can be easily checked if the script block returns value
from property that is not defined to parameter “BasedOnExtensionProperty’. See
the example:

PS> New-VIProperty -Name ToolsVersion -ObjectType
VirtualMachine -Value { param ($vm) return $vm.ExtensionData.Guest.ToolsVersion;
} -BasedOnExtensionProperty ‘Guest.ToolsStatus’


PS> Get-VM | select Name,ToolsVersion

Name                              ToolsVersion

—-                              ————











More on ExtensionData initialization

It should be noticed that ExtensionData is partially filled
up only during the custom properties initialization. Let see the following
sequence of commands:

PS> New-VIProperty -Name ToolsStatus -ObjectType
VirtualMachine -Value { param ($vm) return $vm.ExtensionData.Guest.ToolsStatus;
} -BasedOnExtensionProperty ‘Guest.ToolsStatus’

PS> $vm = Get-VM | Select –First 1

# At this point ExtensionData of the $vm instance is not


PS> $vm.ToolsStatus


# At this point ExtensionData property is initialized, but it is not
fully filled up. Two different list of fields are filled up:

 – Fields needed to be initialized persistent properties
of the instance type

 – Fields pointed to BasedOnExtensionProperty parameter
– in this example ‘Guest.ToolsStatus’


PS> $vm.ExtensionData.Guest.ToolsVersion

# At this point the whole ExtensionData is filled up.
The reason is the direct access to the ExtensionData property which activates
the full retrieval.

Other examples of script based properties

Adding property to all VI objects that shows the name of the
server to which the object belongs.

PS> New-VIProperty -ObjectType VIObjectCore  -Name
VIServerName -Value { param($obj) if ($obj.UId -match
"/VIserver=[\w]+@(.*):.*" ) { return $matches[1] } else { return
"" } }


PS> get-vm test* | select Name,VIServerName  |
Format-Table -AutoSize

Name                              VIServerName

—-                              ————


…                                 …


PS> get-vmhost | select Name,VIServerName | Format-Table

Name          VIServerName

—-          ————


Creating properties that show the total committed space in
MB and the total un-committed space in MB.

PS> New-VIProperty -ObjectType VirtualMachine -Name CommittedSpaceMB
-Value { param($vm) $sum = 0; $vm.ExtensionData.Storage.PerDatastoreUsage |
foreach { $sum += $_.Uncommitted} ; $sum = [int]($sum / 1024 / 1024); return
$sum } -BasedOnExtensionProperty ‘Storage.PerDatastoreUsage.Uncommitted’


PS> New-VIProperty -ObjectType VirtualMachine -Name
UncommittedSpaceMB -Value { param($vm) $sum = 0;
$vm.ExtensionData.Storage.PerDatastoreUsage | foreach { $sum += $_.Uncommitted}
; $sum =

[int]($sum / 1024 / 1024); return $sum }
-BasedOnExtensionProperty ‘Storage.PerDatastoreUsage.Uncommitted’


PS> get-vm test* | select
Name,CommittedSpaceMB,UncommittedSpaceMB | ft -AutoSize

Name                              CommittedSpaceMB

—-                              —————-

8086              20662

32114              14320

3072                  0

testMachine_Vista_32bit_2                     2048               

22529                  0

Pre-defining custom properties


When defining a custom property if there is already defined
property to the same type with the same name New-VIProperty will fail. It is
possible to override definition of existing property using the –Force switch.

Getting and removing custom properties

vSphere PowerCLI has cmdlets Get-VIProperty and Remove-VIProperty.

Both cmdlets allow to filter defined custom properties by type and name.

For example, the following line will remove all defined properties for
the type VirtualMachine

PS> Remove-VIProperty –ObjectType VirtualMachine –Name *


The following line will remove all properties that contains
“space” in their names in all types.

PS> Remove-VIProperty –ObjectType * -Name *space*

PowerCLI Team

VMware vSphere PowerCLI 5.0 is out

Hi all, 

We are glad to announce that VMware vSphere PowerCLI 5.0 is out!!!

You can download it from here – http://vmware.com/go/powercli.

Check the release notes for the full list of new features and improvments.

PowerCLI Team

HA Cluster Improvements

PowerCLI 4.1.1 introduces three new improvements for HA clusters:

  • Ability to edit advanced HA cluster settings
  • Cmdlet that retrieves the primary nodes of HA cluster
  • Set of new properties that contain runtime HA information

The first of the new features is the ability to edit the advanced settings of HA clusters. There are four new cmdlets that allow you to customize HA settings – Get-AdvancedSetting, New-AdvancedSetting, Set-AdvancedSetting, and Remove-AdvancedSetting.

Let’s see several simple actions with these cmdlets:

  • Assign value to isolation address 0 on cluster with name TestCluster
  • Get isolation address 0 for all clusters
  • This command returns all customized settings for a given cluster
  • Update the value of an existing advanced setting for all clusters.
  • Updating can be done also through the New-AdvancedSetting cmdlet and by using the –Force switch. This row adds a value or overrides the already assigned value.
  • Remove a specific customized setting for all clusters.

You can refer to the vSphere Availability Guide for the full list of HA advanced settings.

The second improvement is represented by the Get-HAPrimaryVMHost commandlet. This commandlet returns a list of the primary nodes/hosts for a given cluster and it is really simple to use:

  • Get the primary nodes of a cluster named TestCluster

The third new feature is the addition of new properties in Cluster objects. These properties describe HA cluster runtime information and their names are HATotalSlots, HAUsedSlots, HAAvailableSlots, HASlotCpuMhz, HASlotMemoryMb and HASlotNumVCpus.

For example, let’s see how we can create a report that shows the count of total slots and the count of currently used and available slots.

Snapshot Size

There have been multiple posts in the community about the size of the snapshots and how it should be calculated. There are some issues with the “SizeMB” property of the Snapshot object, so this post will try to explain what these problems are and what is the correct way to calculate snapshot sizes.

We’ll try to keep things simple and not go in too much detail. To start off let’s imagine you have a virtual machine with a single hard disk. This disk is represented as a “vmdk” file in the datastore (e.g. VM.vmdk). Whenever you write something on the hard disk of the VM it is saved in that VM.vmdk file (figure-1). 

When you create a snapshot this VM.vmdk file gets “frozen” and a new one (VM-1.vmdk) is created. The “frozen” VM.vmdk file represents the exact state of the VM’s hard disk at the time when the snapshot was taken. From that point on all changes on the VM’s hard disk are reflected in the new VM-1.vmdk file. Also a new “vmsn” file is created (e.g. Snapshot1.vmsm) which represents the state of the VM’s memory at the time of the snapshot creation (figure-2).


Similarly when a second snapshot is taken VM-1.vmdk gets “frozen” and VM-2.vmdk and Snapshot2.vmsn files are created, the same thing happens when we create a third snapshot (figure-3).


So how is the snapshot size calculated?

For each snapshot the size includes the sizes of the files needed to capture the state of the VM at snapshot time (e.g. hard disk and memory).

For Snapshot2 (figure-3) these files are Snapshot2.vmsn and VM-1.vmdk. The VM-1.vmdk contains all changes made after the first snapshot and it is required part of Snapshot 2.

For the currently active snapshot (e.g. Snapshot3), its size also includes the file which stores disk changes after the snapshot (e.g VM-3.vmdk, figure-3). Thus Snapshot3 files are Snapshot3.vmsn, VM-2.vmdk and VM-3.vmdk. VM-2.vmdk contains all changes since previous snapshot and VM-3.vmdk contains the current changes.

The root snapshot (e.g. Snapshot1) is based directly on the VM’s disk (e.g. VM.vmdk) but its size is not calculated (it’s calculated towards the size of the hard disk itself, not the snapshot). That way the files calculated in the size of each snapshot are the ones marked in orange in figures 2 and 3.

(Note: if we consider figure 3 and imagine that Snapshot2 is the currently active snapshot, then the size of VM-3.vmdk will be calculated in Snapshot2’s size, not Snapshot3’s)

Now for the “SizeMB” property of the Snapshot object. When calculating its value we use the above mentioned approach and calculate the size correctly for ESX 3.0 and 3.5. However there are some changes in the API behavior from 3.5 to 4.0 that we overlooked, thus resulting in wrong calculation of the snapshot size on ESX 4.0.

This issue will be fixed in a future release, but until then you can use the attached script to get the correct snapshot sizes. The script works on all ESX versions and uses the above mentioned approach for calculation.

Download GetSnapshotSize.ps1(fixed)

Dimitar Hristov & Vitali Baruh

PowerCLI Team

ManagedObjectReference Made Easier

PowerCLI 4.1 introduces easier way to initialize ManagedObjectRefernce (MoRef) instances which are necessary while playing with the Get-View cmdlet.

Till now there were several ways to get MoRefs. The most popular one is to get the view object and to use its MoRef property. Another approach is to parse the values of the ID into two parts – type and value.

For example, to convert virtual machine hard disks to thin-provisioned format it is necessary to have the target datastore MoRef: