PowerCLI and the SDK – Part 2 – Prepare the trip

When I publish scripts that use SDK properties or methods, one of the questions that comes back regularly is “Where do you find what to use ?“.
Let me assure you, there are no tricks, optical illusions or black magic involved. I’m simply using the numerous resources that are made available in the VMware Developer community.
Diving into the SDK is like making a big trip, you have to start prepared !
Start of by getting your hands on the vSphere Web Services SDK package.
Extract the files to a local folder

SDK-foldersand you now have access to:

  • the VMware vSphere API Reference Documentation
    • a bit like Google Maps but then for vSphere. It allows you to find your way around and zoom in all the way to “street level” view !
    • Just double-click on the index.html file and you have access to the complete Reference in your browser. No Internet connection required !

    SDK-ref-start

  • several Java and .Net samples
    • As I already remarked in PowerCLI and the SDK – Part 1 no PowerShell examples yet 🙁 But hey, we’re patient and let the fairies do their work 😉 And there is a lot to be learned by looking at the Java and .Net examples.

    SDS-samples

  • the WSDL (Web Services Description Language) files for API 2.0 and API 2.5 (which also covers API 4.0).
    • From the W3C definition: “…an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information

    SDK-WSDL

  • the VMware vCenter Storage Monitoring Service
    • New since vSphere and (as always) still experimental. From the ReadMe page: “…simplified access to all vCenter storage information associated with VMware vCenter servers.“. These APIs are for querying only, no changes can be done through this interface.

    SDK-SMS

While the intended use of the VMware vSphere API Reference Documentation is probably obvious, that of the WSDL files is perhaps less so.

In the W3C definition of a WSDL file it says XML, so I prefer to use XMLPad (see also My PS toolbelt) and it’s Table View.

When we open the bigger of the two WSDL files we see a wealth of information about the SDK.

WSDL-globalDid you know for example, that there are 463 methods you can call via the API ? And did you know that there are 1361 messages/faults these methods can return ?

We can do lots of useful stuff with this file. As an example let’s take the AddHost_Task method.

SDK-method-detailsFrom the above diagram we can see that this method requires a vim25.AddHostRequestType object to be passed. Looking up this vim25.AddHostRequestType we can see which are the parameters that need to be provided to the method.

The parameters are all “standard” types (boolean, string, MoRef) except for the spec parameter which is of the HostConnectSpec type.

We look up this “complex” type and see all it’s elements.

SDK-object-details

Note that the entry also shows which elements are “optional“. These are the ones that have a zero value in the MinOccurs column.

Now all this information is also available in the API Reference as the following screenshots confirm. Also if a parameter is optional or not (see the red asterisk after a property).

The AddHost_Task method …

SDK-AddHost_Task-ref… and the HostConnectSpec object.

SDK-HostConnectSpec-ref

Now we wouldn’t be real PowerShell adepts if we didn’t try to automate this process 😉

Below is my second version of such a script. It can be used in two different ways:

  • looks for a specific method and returns the parameters and whether or not a parameter is required
  • list all methods and their parameters

The major differences with the first version of the script:

  • a better interpretation of the WSDL file
  • stores all the required WSDL information in hash arrays. This means the script will take a bit longer before you see the first output. On the other hand the script will be a lot faster if you want to list all methods
  • the parameters for each method are now in alphabetical order which makes it easier to cross-reference with the Reference Guide
  • the ManagedObjectReference problem is still there, the output only shows the type property but not the value property because this last property is not present in the WSDL file. I started a thread on this in the vSphere Web Services SDK Community

Annotation

Line 1-27: the core function of the script. This function recursively lists all the parameters, their type and, if defined, their minimum and maximum occurence

Line 33: the script uses the vim25 WSDL files. I haven’t tested the script with WSDL files for API 2.0

Line 39-138: these lines create the hash tables with the required WSDL information.

Line 140-148: the first option to use the script is to enter the name of a method in the $tgtMethod variable. The script will then list all the parameters for this one specific method

Line 150-159: the second option will list all 463 methods with their parameters

Some sample runs

AddHost_Task

This is a rather simple method (looking at the parameters at least).

The yellow numbers behind a property indicate what the minimum (and maximum) occurrence of the property may be. In this case we see for example that the port property may be left out.

This is what is indicated in the SDK Reference by the red asterisk behind a property.

SDK-Ref-red-asterisks

When there is no number behind the property, a value for that property has to be provided to the method. One such example is the force property.

ReconfigVM_Task

This produced, as you could have guessed, a rather long list. That’s why I will only show some extracts.

With this method there are two noteworthy points.

  • the backing property (2nd extract) has no further child-properties. That’s because, depending on the device you are manipulating, you will have overlay this property with a more specific object.
  • this method has several properties that need to have Enum type values. For example, the operation property can only have one of these: add, remove or edit

All in all, this script was a personal exercise in getting to know WSDL files. As far as I could see there are no PS scripts/modules that allow you to extract this kind of information from a WSDL file.

The script also allows you to see all the properties for a method in one list. It avoids clicking through all the hyperlinks in the Reference Guide ;-).

In conclusion, you now have your maps (and even some very detailed plans with the script) to start your wonderful trip through SDK land.

More on the actual start of the trip in a next episode in this series.

5 Comments

    Eric Gray

    Outstanding post. I feel smarter after reading this. 🙂

      LucD

      Thanks Eric. Glad you liked it.

    LucD

    As some of you might have noticed there is an issue with the way the script displays the ManagedObjectReference.
    This should be displayed as:

    _this vim25:ManagedObjectReference
    type xsd:string
    value xsd:string

    I’m looking into this “feature”.

Leave a Reply

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

*
*

7 + 15 =

This site uses Akismet to reduce spam. Learn how your comment data is processed.