Documentation is an important part of the automation and development process. When I first started using PowerCLI, I found the docs to be overwhelming and confusing. As my PowerCLI knowledge grew, I started to use them more and more. Instead of frustratingly browsing the multiple levels of properties that make up vCenter objects in a terminal, I found I could easily pick them out in the docs. As part of this blog post, we’re going to walk through the available documentation, which documentation should be used at what points, and then walk-through two use cases of using the documentation to perform a task.

PowerCLI Objects

PowerCLI allows us to access two different types of objects, .Net and vSphere. It’s important to know about these two object types and how to interact with them to understand what documentation should be used at what points.

To summarize the two objects quickly, the .Net objects are what PowerCLI high-level cmdlets interact with. Example: Get-VM returns back a UniversalVirtualMachineImpl .Net object. The vSphere objects are what the low-level cmdlets interact with, which is a direct connection to the vSphere Web Services API. These vSphere objects are accessible through Get-View and when referencing a .Net object’s ExtensionData property. Example: (Get-VM).ExtensionData returns back a VirtualMachine vSphere object.

If there’s a question about what object type we’re interacting with, we can verify what object type by using either the object level method of ‘GetType’ or with the Get-Member cmdlet. Here’s how we can use the GetType method against the three examples I’ve already mentioned: Example: Retrieving an Object’s Type

These two object types also have their own sets of documentation. The .Net objects are available in the “Types” section of the PowerCLI Cmdlet Reference. The vSphere objects are available in the vSphere Web Services API Reference. The vSphere API has two main object types we’ll want to become familiar with, Managed Objects and Data Objects. Think of Managed Objects as the top-level inventory items, such as Datacenters, Clusters, Hosts, and VMs. It’s also worth noting that Managed Objects can also be services, such as the EventManager and ScheduledTaskManager, but we won’t be using them as part of this blog post. We can then think of Data Objects as the child objects that make up the top-level Managed Objects.

If you want to learn some more about these two objects and how they pertain to PowerCLI, PowerCLI mastermind Luc Dekens and I walked through these in a VMworld session last year: A Deep(er) Dive with PowerCLI 10 (VIN1992BE)

Documentation Lingo

At first glance, the documentation for both PowerCLI and the vSphere APIs can be a little overwhelming. There’s a lot of information available to consume. Let’s cover the main sections that are consistently available for both object types. These sections are: Property of, Parameter to, Returned by, Extends and/or Extended by, and Properties. “Property of” means that this particular object will be returned as a property for the listed objects. “Parameter to” means this object can be used as input for a particular cmdlet and/or method. “Returned by” means that a particular object will be the response by a cmdlet and/or method. Then we have “Extends” and/or “Extended by”, which is interesting because these can actually add properties to the given object which may not be listed in the documentation since it can change based on the object being referenced. Lastly, there are the “Properties” which are the items and objects that make up each object. Every time you get an object based response in PowerCLI, you’ll find those properties.

Next, we’re going to put all of this information to use in order to solve an issue where we’re looking for more information about a VM’s disk space and its associated filesystem.

Documentation Walk-Throughs

I’m planning to work on several walkthroughs and sharing them as they have been completed. The list will begin to accrue below:

If you think of a scenario that you’d like to see covered, please do let me know.