To be done: write about general structure and behavior of the API, e.g.: Folders(not "real" Folders, two points of view - ressource and organization)

Hi there,

in this thread I'll just let you know how I struggeled the API for the last two months and, hopefully, make sure you don't have to too. I've been able to accomplish at least the most of what I wanted but it took me days to find solutions to specific problems. While I had to struggle with incomplete documentation or missing answers to years old questions, I hope you can follow the path of "debugging" I tend to walk along nowadays. I used C# and the vSphere PowerCLI Toolkits VMware.Vim.dll, which enables you to use nice high level features as well as get specific things done.

First off, how to get started?

I chose the, in my opinion, simplest way to program against the API with the vSpherePowerCLI Toolkit. Once again, VMware, please provide more information about how to choose the API. And also mention that everything is nicely possible with this little VMware.Vim.dll with nice Wrapper types for all objects.

Good Part: You don't have to build anything, and you just start right ahead with VisualStudio 2010 and a single reference.

Just download the PowerCLI packagehttp://www.vmware.com/support/developer/PowerCLI/index.html and install it. Then just set the reference in your project to the VMware.Vim.dll in your freshly installed folder ( for me, that was: C:\Program Files (x86)\VMware\Infrastructure\vSphere PowerCLI\VMware.Vim.dll) on Windows 7. And then you can start coding with "using VMware.Vim;" and there you go!

VimClient vmc = new VimClient();
 
vmc.Login(<credentials go here>);

Notes: You will always want to keep an instance of the VimClient arround in order to be able to operate on the ManagedObject on the vSphere Server.

CAUTION: Sometimes, it seems to be broken when you instantiate an object with the typical:

// Seems to use the constructor of the class itself and instantiates itself with 
// the VimClient to get its data from vCenter...
T t = new T(<vimclient>, <managed object reference>);

If so, try using the:

// instead of null you could also provide properties, which I never needed.
T t = (T) vimclient.GetView(<managed object reference>, null); 

You will run into errors. Then it's time to debug!

Lets DEBUG!

I suggest you to do a step by step debug to ensure the source of the error is not misleading your thoughts. First off, go to the website of the ManagedObjectBrowser(MOB), which can be found by browsing to:

https://w.x.y.z/mob where w.x.y.z is the IP of your vSphere Server.

Then, click on ServiceContent and in the appearing window click Invoke! Now you can look at the vSphere Server from the API perspective. Browse to the Folder or whatever you struggle with. Then take a look at the ManagedObjectReference in order to double check that while you Debug, you see

the same ManagedObjectReference in your code. If you are not sure on how to retrieve this, I am always taking the "secure" way over the ViewBase:

// now place the type of object you want to see as T in the line beneath:
T t = (T) vmc.GetView(new ManagedObjectReference(<String from MOB seen reference>, null));

While debugging, set a breakpoint to the line above. Then you'll be able to how this worked out.

Also you'll get a feeling on how to use the API when you browse the vSphere Inventory in the MOB.

A word on ManagedObjects

If you try to find something you want to gather informations from or you want to modfiy an object, I suggest you follow more than one path.

My approach here is to use three different methods to find things. I have a sort of string concatenation class that does some path concatenation for finding objects by inventory paths. This is extremely useful because you don't rely on Managed Object references that you might not even know.

Here is how you can get going:

https:/1.1.1.1/mob/?moid=SearchIndex

And then you have the following options to reach for objects:

It's super useful to check wether you have all paths in the right place and also to look up some of the entities that you don't want

to click through the whole inventory structure.

One example path you could throw in "FindByInventoryPath" for testing purposes:

/<Name of Datacenter>/host/<Name of ClusterComputeResource>/Resources

This will directly lead you to your Clusters resources MOR from a programs viewpoint.

Now the Programatical part; I've just build up a method for this:

/// <summary>
/// Returns a ManagedObjectReference from an inventory path
/// </summary>
/// <param name="vmc">The client to be used</param>
/// <param name="path">Path of the Entity to be found</param>
/// <returns>the MoRef found by path</returns>
public static ManagedObjectReference findManagedObjectReferenceByPath(VimClient vmc, String path)
{
    // Inventory Searching Instance of SearchIndex
    SearchIndex searcher = (SearchIndex)vmc.GetView(vmc.ServiceContent.SearchIndex, null); // new SearchIndex(vmc, vmc.ServiceContent.SearchIndex);
    ManagedObjectReference result;
    try
    {
        result = searcher.FindByInventoryPath(path);
    }
    catch (Exception e)
    {
        throw new MyNamespace.Exceptions.PathNotFoundException("While trying findManagedObjectReferenceByPath( " + path + "), an InnerException occured.", e);
    }
 
    if (result != null)
    {
        return result;
    }
    else
    {
        throw new MyNamespace.Exceptions.PathNotFoundException("Couldn't find anything by the path: " + path);
    }
}
 
 
 

And btw. with this apprach, you can look at the GUI of vCenter ti guess the right paths...

Useful Documentation

What I made sticky on my browser while developing the application are the following pages:

• API Overview and "nice" lookup for Properties and methods: http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/
• The MOB of my vSphere Server, which is used by far the most of times, e.g.: https://1.1.1.1/mob
• This communities threads page: http://communities.vmware.com/community/vmtn/developer/forums/managementapi?view=discussions which is sadly the least best source of information. Why? Nobody answers questions and it takes weeks if you get one that helps. But always search first before starting a new diskussion.

I know I know, this is not complete, but please provide feedback with your first struggles in order to complete this thing.

Nevertheless, I hope this helps, at least a bit!

Greetings,

Kjellski

P.S.: I hope somebode will make this thread sticky and or suggest feedback for making it richer.