Home > Blogs > VMware PowerCLI Blog


Let’s Make New-VIProperty Easier

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:

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.

clip_image002

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.

clip_image004

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.

clip_image006

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.

clip_image008

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.

clip_image010

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.

clip_image012

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:

clip_image014

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.

clip_image016

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’).

clip_image018

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.

clip_image020

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:

clip_image022

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.

clip_image024

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

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.

 

imageThis post was created by Vitali Baruh…

Vitali joined VMware and PowerCLI team in the beginning of 2009. He is member of the quality engineering part of the team and his main role is the functional verification of the vSphere, vCloud and License PowerCLI components.

As all members of the team he is working to deliver a good and valuable product. He is also working to improve all processes and tools involved in product development and validation.

This entry was posted in Advanced, Extensions, Reporting and tagged on by .
Alan Renouf

About Alan Renouf

Alan Renouf is a Product Manager at VMware focusing on Automation Frameworks and CLI, he is responsible for providing the architects and operators of the cloud infrastructure with the toolkits/frameworks and command-line interfaces they require to build a fully automated software-defined datacenter. Alan is a frequent blogger at http://blogs.vmware.com/PowerCLI and has a personal blog at http://virtu-al.net. You can follow Alan on twitter as @alanrenouf.

One thought on “Let’s Make New-VIProperty Easier

  1. LucD

    Now this is a useful module !

    Enjoy the vSphere API without having the SDK Reference on your nightstand :-)
    The Get-VIPropertyHelperObject function alone is already sufficient reason to install this module on your station.

    I would surely like to see this module included in the next PowerCLI distribution.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>