New-VIProperty is a powerful PowerCLI cmdlet and it has been a part of the product since PowerCLI version 4.1. Several releases later, we are under the impression that it is still not widely used. If you take a look around the community, it is easy to find scripts which will would be easier to understand and also work faster if they were refactored to use the New-VIProperty cmdlet.
This blog post is not about how New-VIProperty works. There are several great blog posts on the internet which already explain how the cmdlet works and what its benefits are. Some of them are:
- LucD’s blog: Introduction to New-VIProperty – http://www.lucd.info/2010/07/13/powercli-4-1-brings-the-new-viproperty-cmdlet/
- Arnim van Lieshout’s blog: A great blog post about the performance of custom properties created with New-VIProperty – http://www.van-lieshout.com/2010/09/why-new-viproperty-matters/
- Jonathan Medd’s blog: A blog post about New-VIProperty and LucD’s VIProperty module – http://www.jonathanmedd.net/2011/08/using-powercli-viproperties-and-the-viproperty-module.html
- The PowerCLI blog: A blog post which explains in detail what happens under the hood of custom properties – http://blogs.vmware.com/vipowershell/2011/08/ability-to-customize-vi-objects.html
- LucD’s blog (again): A list of useful VI properties (downloadable as a PS module) http://www.lucd.info/viproperties/
We understand that using New-VIProperty is not that easy. There are a lot of things that should be considered when you create a property – the name of the type you want to customize, the name of the API property, etc.
This blog post includes a PS module whose purpose is to make the use of New-VIProperty easier, the module can be downloaded from here.
Once you import this module into your PowerCLI session, you will be able to:
- Benefit from tab-completion for the New-VIProperty cmdlet
- Inspect which types are customizable with New-VIProperty
- Inspect the properties of a particular customizable type in depth
Let’s take a look at the tab-completion feature
We can start creating a new property by entering “New-VIProperty –ObjectType“. Then, if we press the Tab key, we will iterate through the valid values for the ObjectType parameter.
Of course, when we know the first letters of the type we want to customize, we can enter them before pressing the Tab key. In this case, pressing the Tab key will iterate only through the types whose names start with the provided letters.
In the screen above, pressing the Tab key will show types like VirtualMachine, VirtualPortgroup, VirtualSwitch, etc.
If we are creating a value-based property, after the type has been defined, we should specify the API property with the –ValueFromExtensionProperty parameter. Now this is much easier using tab-completion.
So the type is VirtualMachine, and let’s say we want to add ToolsVersion. It is part of the Guest API property. So we can just enter “G” and then press Tab key. This time the tab-completion feature will search for all properties starting with “G” within the VirtualMachine backing API type. The first match is “Guest”.
After that we should add a dot and start pressing Tab until the desired property appears.
The Guest property has several sub-properties and after several hits on the Tab key we will reach the “ToolsVersion” property. The only thing left to do is give our new property a name. We will do this manually.
Tab-completion also works for the –BasedOnExtensionProperty parameter when you are creating a script-based property.
The second enhancement is the ability to retrieve the list of customizable types
The provided PS module exports the Get-VIPropertyValidTypeNames function. By default, it returns the complete list of types which we can customize using New-VIProperty.
Each type is represented by a PSObject with the following properties:
- TypeName – represents the string that New-VIProperty accepts through the ObjectType parameter
- IsManaged – indicates whether the backing API type is managed or not. For more information about managed and data object types, see the vSphere API SDK documentation
- VimTypes – a list of the backing API types. Knowing which is the backing type of a cmdlet type could be useful; for example, we can refer to the vSphere API SDK documentation for a more detailed description of the API type.
The function provides three filter parameters which let you reduce the list of types. Run “Get-Help Get-VIPropertyValidTypeNames” for more information.
The last enhancement is another function named Get-VIPropertyHelperObject.
This function accepts the name of a customizable type and returns a helper PSObject which could be used for:
- Inspecting the backing API type
- Searching API type properties by name
- Creating VI properties easily
Let’s see this in action. Let’s pass VMHost to the function and save the result in the $helper variable.
The structure of the helper object is based on the backing API object. It has the same set of properties, but their purpose is informative. The output of this object looks like this:
At the top we can see the cmdlet type –VMHost – and the backing API type – HostSystem.
The list of all API type properties follows. For each property, the type is also displayed.
A plus symbol in front of the property indicates that it has sub-properties and it is browsable. For example, if you write $helper.Config, you will see all the properties of Config.
The helper object also has a method named SearchProperties. It searches all properties and sub-properties by name.
Let’s assume that we want to add a property to all VMHosts which shows the vendor of the hardware box. We also know that there is a ‘Vendor’ property in the API object, but we are not sure where it is defined, so we can call $helper.SearchProperties(‘Vendor’).
The output contains all properties whose names contain ‘Vendor’. The last one is the property that we’re looking for.
The next step is creating a property and this is really easy with the helper object. The only thing that we have to do is to call this line: $helper.Summary.Hardware.Vendor.CreateValueProperty()
The helper object provides an identical method for each property within the whole structure. This method creates a VI property using the New-VIProperty cmdlet.
We can see that the method first shows the New-VIProperty expression which will be executed. Below this line, you can see the result of running the New-VIProperty cmdlet.
Let’s see the result of our actions:
This method is really useful for an interactive PowerCLI session, but what about if we want to create a VI property within a script. The helper object provides two methods named GetValuePropertyCreationCode and GetScriptPropertyCreationCode.
Both methods build and return a New-VIProperty expression which you can copy, paste and modify in your script.
Three of the methods have a parameter which accepts the name of the new VI property. If it is not specified (as it is not in the examples), a name will be selected automatically.
Summary
In conclusion, this module allows you to:
- Inspect API types easily and search their properties by name
- Create VI properties or generate New-VIProperty expressions to use in a script
- Retrieve the list of customizable types
- Use tab-completion within the New-VIProperty cmdlet
Finally, let’s see where New-VIProperty is applicable and why it is better to use:
-
- If you have a Select expression using hash table syntax
- Get-X | Select-Object -Property Name,@{Name=”NestedPropertyName”;Expression={<some expression over $_>}}
- If your script needs data from the ExtensionData/View
- foreach ($vm in $vms) { ….. $foo = $vm.ExtensionData.foo …..}
- The code look better
- The scripts are faster
- If you have a Select expression using hash table syntax
Download
Download the module from here and import it into your session.
What Next?
If you find this module helpful or have any other comments on this feature we would love to hear them, the PowerCLI team at VMware constantly tries to make PowerCLI a better product and a product which is easy to use, let us know what you think of this and if you would like to see things like this backed into the release of PowerCLI.
|
