Home SDK

This page is dedicated to SDK best practices/tips & tricks for the PowerCLI user.

The idea came from Steve Jin‘s best practices posts. See

I thought it would be useful to show how some of Steve’s best practices translate for the PowerCLI user.

There are also a lot of excellent tips and tricks present in the PowerCLI Community. But finding them is not always an easy task.

If you have questions or suggestions, please mail them to sdk@lucd.info .

[toc depth="1" listtype="ul" title="Contents"]

Handle Faults Carefully

This is a best practice that is often overlooked in the PowerCLI world. Unjustified, since there is a wealth of information available in the error property of the TaskInfo object.

If you’re writing a PowerCLI script that should behave correctly, the script should contain the proper error handling.

As an example, take the New-dvSwPVLAN function I wrote in my dvSwitch scripting – Part 6 – Private VLAN post.

If you forget to provide the correct ConfigVersion value, the call to the ReconfigureDvs_Task method will fail. In the vSphere client you will see the message “Cannot complete operation due to concurrent modification by another operation“. This doesn’t really tell you what is wrong with your script.

But with the addition of a few extra lines in your script, you will get a message that explains what went wrong much clearer.

With these extra lines, the following lines will be displayed on the console and the script will exit.

This method also avoids that the script will have to contain a huge switch-case construction to handle the 200+ types of faults that can occur.

Choose the Right APIs – Versioning

Most of the time VMware takes care that a new API version is downward compatible. But sometimes there are minor, but significant for you as a scripter, differences.

An example that popped-up several times in the PowerCLI Community is the call to the SearchDatastoreSubFolders_Task method. In API 4.0 the FileQueryFlags object has a new property called fileOwner. The result was that scripts that worked in API 2.x environments, didn’t work anymore in API 4.0 environments. See the Way to report on Orphaned .VMDK files post for more details.

The point I’m trying to make here is that it is quite easy to make your script work in several API environments. Just test what API version you are running against by checking the Client.Version property.

Thanks to Yasen Kalchev for the solution. Yasen is one of the developers on the PowerCLI Team.

Collect Only What You Really Need

The PowerCLI Team already provided support for this best practice some builds ago with the UpdateViewData method.

As you probably know, the .Net objects that you get in PowerCLI contain read-only copies of the vSPhere objects. These .Net objects are not automatically refreshed when one or more of the properties change. For that reason the UpdateViewData method was introduced.

With this method you can refresh your .Net copy completely or only specific properties. If you only need to use a specific property it is advised to only refresh that property.

As an example, let’s take

A more efficient way of doing this would be