vSphere Web Services
`SDK Programming Guide
`
`17 APR 2018
`VMware vSphere 6.7
`vCenter Server 6.7
`VMware ESXi 6.7
`
`WIZ, Inc. EXHIBIT - 1015
`WIZ, Inc. v. Orca Security LTD.
`
`

`

`vSphere Web Services SDK Programming Guide
`
`You can find the most up-to-date technical documentation on the VMware website at:
`https://docs.vmware.com/
`If you have comments about this documentation, submit your feedback to
`docfeedback@vmware.com
`
`VMware, Inc.
`3401 Hillview Ave.
`Palo Alto, CA 94304
`www.vmware.com
`
`Copyright © 2011–2018 VMware, Inc. All rights reserved. Copyright and trademark information.
`
`VMware, Inc.
`
` 2
`
`

`

`Contents
`
`About This Book 12
`
`
`
`
`
`
`
`1 VMware vSphere and the vSphere Web Services SDK 14
`vSphere Web Services SDK 14
`SDK Developer Setup for the Web Services SDK 15
`SDK Samples for the Web Services SDK 15
`UML Diagrams Used in the Web Services SDK Programming Guide 15
`
`2 vSphere Web Services API Programming Model 16
`vSphere Client-Server Architecture 16
`Web Services API as a Web Service 17
`WSDL Files and the Client-Side Proxy Interface 17
`Network Access to the vSphere Web Service 18
`Language-Specific Classes and Methods 19
`Mapping XML Data Types to Java and C# Data Types 20
`Access to Managed Objects 20
`Access to vSphere Server Data 21
`Obtaining Information from a Server 21
`Working with Data Structures 22
`Accessing Property Values 22
`Nested Properties and Property Paths in Composite Data Structures 23
`xsd:anyType Arrays 23
`Indexed Array and Key-Based Array Properties 26
`Unset Optional Properties 26
`Escape Character in Name and Path Properties 27
`
`3 Client Applications for the Web Services API 28
`vCenter Server Connections 28
`Establishing a Single Sign-On Session with a vCenter Server 29
`LoginByToken to vCenter Server By Using C# 29
`vCenter Server Single Sign On Session Using C# 29
`Persistent vCenter Server Sessions 30
`Sample Code 30
`Using LoginByToken in C# 30
`LoginByToken to vCenter Server By Using Java 36
`vCenter Server Single Sign-On Session Using Java 36
`HTTP and SOAP Header Handlers in Java 36
`Creating the HTTP Connection in Java 38
`
`VMware, Inc.
`
` 3
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Using LoginByToken in Java 39
`Establishing a Session with Username and Password Credentials 42
`Overview of a Java Sample Application for the Web Services SDK 42
`Build a Simple vSphere Client Application for the Web Services SDK 43
`Java Client Example for the Web Services SDK 44
`Web Server Session Token 46
`Accessing the vSphere Web Services HTTP Endpoint with JAX-WS 47
`Accessing the vSphere Server from a Web Services Client 49
`Closing the Connection from a Web Services Client 50
`Using the Java Samples as Reference 50
`Multiple Versions of the vSphere API 52
`Java and C# Sample Applications in the Web Services SDK 53
`Java Samples in the Web Services SDK 53
`C# Samples in the Web Services SDK 53
`
`
`
`
`
`4 Datacenter Inventory 55
`Inventory Overview for the Web Services SDK 55
`Inventory Hierarchies and ServiceInstance 55
`Folders in the Hierarchy 56
`ESXi Inventory Hierarchy 57
`Accessing Inventory Objects 57
`Creating Inventory Objects 58
`Privileges Required for Inventory Management 59
`Privileges 59
`Permissions 59
`Managed and Standalone ESXi Hosts 60
`
`5 Property Collector 62
`Introduction to the PropertyCollector 62
`Data Retrieval 63
`Inventory Traversal and Object Selection 63
`vSphere Data Objects for Property Collection 63
`vSphere Methods for Property Collection 64
`Retrieve Properties with the PropertyCollector 64
`Simple Property Collector Program in Java for Web Services SDK 67
`Inventory Traversal 72
`TraversalSpec Traversal 72
`Traverse the Inventory By Using the Property Collector 74
`Inventory Traversal Example in Java 75
`SelectionSpec Traversal 80
`Client Data Synchronization (WaitForUpdatesEx) 86
`Property Filters 87
`
`VMware, Inc.
`
` 4
`
`

`

`vSphere Web Services SDK Programming Guide
`
`WaitForUpdatesEx 87
`Server Data Transmission 89
`PropertyCollector Performance 89
`SearchIndex 90
`
`6 Authentication and Authorization 91
`Objects for Authentication and Authorization Management 91
`Authentication and Authorization for ESXi and vCenter Server 92
`ESXi User Model 93
`vCenter Server User Model 94
`vSphere Security Model 94
`Setting Up Users, Groups, and Permissions 96
`Obtaining User and Group Information from UserDirectory 96
`RetrieveUserGroups Method 97
`Managing ESXi Users with HostLocalAccountManager 97
`Methods Available for Local Account Management 98
`Create a Local User Account on an ESXi System 98
`Managing Roles and Permissions with AuthorizationManager 99
`Using Roles to Consolidate Sets of Privileges 100
`Modifying Sample Roles to Create New Roles 101
`Granting Privileges Through Permissions 102
`Authenticating Users Through SessionManager 104
`Using VMware Single Sign On for vCenter Server Sessions 105
`Using the Credential Store for Automated Login 105
`Credential Store Libraries 106
`Credential Store Methods 106
`Credential Store Backing File 107
`Credential Store Samples 107
`Specifying Roles and Users with the Credential Store 108
`Managing Licenses with LicenseManager 109
`
`7 Hosts 110
`Host Management Objects 110
`Retrieving Host Information 111
`Configuring and Reconfiguring Hosts 112
`Managing the Host Lifecycle 112
`Reboot and Shutdown 112
`Using Standby Mode 112
`Disconnecting and Reconnecting Hosts 113
`Querying and Changing the Host Time 113
`Querying Virtual Machine Memory Overhead 114
`
`
`
`
`
`
`
`VMware, Inc.
`
` 5
`
`

`

`vSphere Web Services SDK Programming Guide
`
`8 Storage 115
`Storage Management Objects 115
`Introduction to Storage 116
`How Virtual Machines Access Storage 117
`Datastores 118
`Choosing the Storage API to Use 119
`Managed Objects for Working with Storage 120
`Configuring Disk Partitions 120
`Multipath Management 121
`Configuring iSCSI Storage 121
`Configure the VMkernel To Support Software iSCSI 122
`Configure iSCSI Initiators 123
`Creating and Managing Datastores 124
`Accessing Datastores 125
`Creating and Modifying a VMFS Datastore 125
`Removing and Updating Datastores 127
`Managing VMFS Datastores with HostStorageSystem 127
`Managing VMFS Volume Copies (Resignaturing) 128
`Resignaturing Volumes with ResignatureUnresolvedVmfsVolume_Task 129
`Managing Diagnostic Partitions 129
`Retrieving Diagnostic Partition Information 130
`Create a Diagnostic Partition 130
`Sample Code Reference 131
`
`
`
`9 vSphere Networks 132
`Virtual Switches 132
`Port Groups 132
`Virtual Machine Network Interfaces 133
`VMkernel Network Interfaces 133
`Physical Network Adapter (pnic) 134
`Using a Distributed Virtual Switch 134
`Distributed Virtual Switch Configuration 135
`Backup, Rollback, and Query Operations 136
`VMware Standard Virtual Switch 137
`Configuring a Standard Virtual Switch 137
`vNetwork Standard Switch Environment 138
`Setting Up Networking with vSS 139
`Defining the Host Network Policies 141
`NIC Teaming 141
`Setting Up IPv6 Networking 142
`Adding Networking Services 143
`Sample Code Reference 144
`
`VMware, Inc.
`
` 6
`
`

`

`vSphere Web Services SDK Programming Guide
`
`
`
`
`
`10 Virtual Machine Configuration 146
`VirtualMachine Management Objects and Methods 146
`Creating Virtual Machines and Virtual Machine Templates 147
`Creating a Virtual Machine Using VirtualMachineConfigSpec 147
`Creating Virtual Machine Templates 149
`Cloning a Virtual Machine 149
`Converting a Template to a Virtual Machine 150
`Accessing Information About a Virtual Machine 150
`Configuring a Virtual Machine 151
`Name and Location 152
`Hardware Version 153
`Boot Options 153
`Operating System 154
`CPU and Memory Information 154
`Networks 155
`Fibre Channel NPIV Settings 156
`File Locations 156
`Adding Devices to Virtual Machines 157
`Performing Virtual Machine Power Operations 158
`Registering and Unregistering Virtual Machines 160
`Customizing the Guest Operating System 160
`Installing VMware Tools 161
`Upgrading a Virtual Machine 162
`
`11 Virtual Machine Management 163
`Virtual Machine Migration 163
`Cold Migration 164
`Migration with VMotion 164
`Using Storage VMotion 164
`Snapshots 164
`Creating a Snapshot 165
`Reverting to a Snapshot 166
`Deleting a Snapshot 166
`Linked Virtual Machines 166
`Linked Virtual Machines and Disk Backings 166
`Creating a Linked Virtual Machine 167
`Instant Clone Virtual Machines 169
`Removing Snapshots and Deleting Linked Virtual Machines 175
`Relocating a Virtual Machine in a Linked Virtual Machine Group 175
`Promoting a Virtual Machine's Disk 176
`Performing Advanced Manipulation of Delta Disks 177
`
`VMware, Inc.
`
` 7
`
`

`

`vSphere Web Services SDK Programming Guide
`
`
`
`
`
`12 Virtual Machine Encryption APIs 178
`How Virtual Machine Encryption Protects a Datacenter 178
`What Keys are Used 178
`What Is Encrypted 179
`What Is Not Encrypted 179
`Who Can Perform Cryptographic Operations 180
`How Can I Perform Cryptographic Operations 180
`vSphere Virtual Machine Encryption Components 180
`Key Management Server 181
`vCenter Server 181
`ESXi Hosts 182
`Encryption Process Flow 182
`Prerequisites and Required Privileges for Encryption Tasks 183
`Cryptography Privileges and Roles 183
`Host Encryption Mode 183
`Encrypted vSphere vMotion 184
`API Methods for vSphere Virtual Machine Encryption 184
`vSphere API Methods for KMS Management 184
`API Methods to Prepare an ESXi Host 185
`vSphere API Methods for Cryptographic Operations 186
`SPBM API Methods for Encryption 187
`Workflows for vSphere Virtual Machine Encryption 187
`Set Up the Key Management Server Cluster 187
`Create an Encryption Storage Policy 190
`Create an Encrypted Virtual Machine 193
`Clone an Encrypted Virtual Machine 194
`Encrypt an Existing Virtual Machine or Disk 195
`Decrypt an Encrypted Virtual Machine or Disk 195
`Encrypt Using Different Keys 196
`Recrypting Encrypted Virtual Machines 197
`Encrypted vSphere vMotion 198
`Virtual Disk Manager 198
`Best Practices 199
`
`13 Virtual Applications 201
`About Virtual Applications 201
`Management Overview 201
`Direct and Linked Children 202
`OVF Packages 203
`Creating a VirtualApp 203
`Managing VirtualApp Children 204
`
`VMware, Inc.
`
` 8
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Exporting a Virtual Application 204
`VirtualApp and OvfManager Methods 205
`VirtualApp Data Structures 206
`OvfManager Data Structures 207
`Example of Generating an OVF Package 208
`Importing an OVF Package 209
`Virtual Application Life Cycle 210
`Powering a Virtual Application On or Off 210
`Unregistering a Virtual Application 211
`Suspending a Virtual Application 211
`Destroying a Virtual Application 211
`
`
`
`
`
`14 Resource Management 212
`Resource Management Objects 212
`Introduction to Resource Management 213
`Resource Allocation 213
`Resource Pool Hierarchies 214
`Resource Pool Management Guidelines 214
`Cluster Overview 215
`Creating and Configuring Resource Pools 215
`Understanding Expandable Reservation 216
`Deleting Child Resource Pools 217
`Moving Resource Pools or Virtual Machines Into a Resource Pool 217
`Introduction to VMware DRS and VMware HA Clusters 218
`VMware DRS 218
`VMware HA 219
`Creating and Configuring Clusters 219
`Creating a Cluster 219
`Adding a Host to a Cluster 220
`Reconfiguring a Cluster 220
`Managing DRS Clusters 221
`Managing HA Clusters 221
`Primary and Secondary Hosts 221
`Failure Detection and Host Network Isolation 222
`Using VMware HA and DRS Together 222
`
`15 Tasks and Scheduled Tasks 224
`Creating Tasks 224
`Session Persistence 225
`Cancelling a Task 225
`Using TaskInfo to Determine Task Status 225
`Monitoring TaskInfo Properties 226
`
`VMware, Inc.
`
` 9
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Accessing and Manipulating Multiple Tasks 227
`Gathering Data with a ViewManager Object 228
`Gathering Data with a TaskManager Interface 238
`Understanding the ScheduledTaskManager Interface 240
`Scheduling Tasks 241
`Cancelling a Scheduled Task 244
`Using a TaskHistoryCollector 245
`Managing the HistoryCollector 245
`Sample Code Reference 246
`
`
`
`
`
`16 Events and Alarms 248
`Event and Alarm Management Objects 248
`Understanding Events 249
`Managing Events with EventManager 249
`Event Data Objects 250
`Formatting Event Message Content 251
`Creating Custom Events 251
`Using an EventHistoryCollector 253
`Creating an EventHistoryCollector Filter 254
`Managing the HistoryCollector 254
`Using Alarms 254
`Obtaining a List of Alarms 255
`Creating an Alarm 255
`Defining Alarms Using the AlarmSpec Data Object 256
`Specifying Alarm Trigger Conditions with AlarmExpression 257
`Specifying Alarm Actions 258
`Deleting or Disabling an Alarm 259
`Sample Code Reference 259
`
`17 vSphere Performance 261
`vSphere Performance Data Collection 261
`PerformanceManager Objects and Methods 263
`Retrieving vSphere Performance Data 265
`Performance Counter Example (QueryPerf) 266
`Large-Scale Performance Data Retrieval 274
`Using the QueryPerf Method as a Raw Data Feed 275
`Comparison of Query Methods 275
`Retrieving Summary Performance Data 276
`Performance Counter Metadata 276
`PerfCounterInfo 276
`Performance Intervals 277
`ESXi Server Performance Intervals 278
`
`VMware, Inc.
`
` 10
`
`

`

`vSphere Web Services SDK Programming Guide
`
`vCenter Server Performance Intervals 278
`vSphere Performance and Data Storage 279
`Modifying Historical Intervals 279
`Modifying Performance Counter Collection Levels 280
`Sample Code Reference 281
`
`18 Diagnostics and Troubleshooting 283
`Troubleshooting Best Practices 283
`Overview of Configuration Files and Log Files 284
`ESXi Log File 285
`Virtual Machine Log Files 285
`vCenter Server Log Files 286
`Modifying the Log Level to Obtain Detailed Information 286
`Setting the Log Level on ESXi Systems 287
`Generating Logs 287
`Setting the Log Level on vCenter Server Systems 288
`Using DiagnosticManager 288
`Using the MOB to Explore the DiagnosticManager 290
`Generating Diagnostic Bundles 291
`Export Diagnostic Data By Using the vSphere Client 291
`
`19 Managed Object Browser 292
`Using the MOB to Explore the Object Model 292
`Accessing the MOB 292
`Using the MOB to Navigate the VMware Infrastructure Object Model 293
`Using the MOB to Invoke Methods 294
`Passing Primitive Datatypes to Method 294
`Passing Arrays of Primitives to Methods 294
`Passing Complex Structures to Methods 295
`Using the MOB Along With the API Reference 298
`
`20 HTTP Access to vSphere Server Files 300
`Introduction to HTTP Access 300
`URL Syntax for HTTP Access 301
`Datastore Access (/folder) 301
`Host File Access (/host) 302
`Update Package Access (/tmp) 303
`Privilege Requirements for HTTP Access 303
`
`21 Sample Program Overview 304
`Java Sample Programs (JAXWS Bindings) 304
`C# Sample Programs 308
`
`
`
`
`
`
`
`
`
`VMware, Inc.
`
` 11
`
`

`

`About This Book
`
`The vSphere Web Services SDK Programming Guide provides information about developing applications
`using the VMware® vSphere Web Services SDK 6.7.
`VMware provides different APIs and SDKs for various applications and goals. The vSphere Web Services
`SDK targets developers who create client applications for managing VMware® vSphere components
`available on VMware ESXi and VMware vCenter Server systems.
`
`To view the current version of this book as well as all VMware API and SDK documentation, go to
`http://www.vmware.com/support/pubs/sdk_pubs.html.
`
`Revision History
`This book is revised with each release of the product or when necessary. A revised version can contain
`minor or major changes. The following table summarizes the significant changes in each version of this
`book.
`
`Table 1. Revision History
`Revision Date
`Description
`
`17APR2018
`
`vSphere 6.7 - GA
`Added Instant Clone material to VM Management chapter.
`Minor updates elsewhere.
`
`12APR2017
`
`Removed appendix with list of permissions. Was not maintained.
`
`15NOV2016
`
`vSphere 6.5 - GA
`Added chapter about vSphere virtual machine encryption.
`Removed description of deprecated CIM Storage Management API.
`Updated information about session cookie management.
`
`04SEP2015
`
`Updated information about migrating VMs with VMotion across data centers.
`
`12MAR2015
`
`vSphere 6.0 - Rewrote “Exporting a Virtual Application” section in Virtual Applications chapter.
`
`19SEP2013
`
`10SEP2012
`
`vSphere 5.5 – Added a C# example of using LoginByToken; clarified limitation for HA clusters.
`
`vSphere 5.1 – Added information about using the SessionManager.LoginByToken method; added information
`about distributed virtual switches.
`
`VMware, Inc.
`
` 12
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Table 1. Revision History (Continued)
`Revision Date
`Description
`
`24AUG2011
`
`vSphere 5.0 - Revised performance manager chapter. Added information about: unset properties, using
`vCenter to access host data, and using the QueryConfigOption to add devices; emphasized ListView instead of
`TaskManager; clarified limits and limitations of Linked Virtual Machines; updated samples in chapters 3,5,14,
`and 16; replaced information about Axis bindings with JAX-WS; and updated paths to samples supplied with
`SDK.
`
`13JUL2010
`
`Restructured manual and added chapters about host, storage, and networking. Revised property collector
`chapter and added appendix about HTTP access.
`
`07MAY2009
`
`vSphere Web Services SDK 4.0 Programming Guide.
`
`Intended Audience
`This book is intended for anyone who needs to develop applications using the vSphere Web Services
`SDK. Developers typically create client applications using Java or C# (in the Microsoft .NET environment)
`targeting VMware vSphere. An understanding of Web Services technology and some programming
`background in one of the stub languages (C# or Java) is required.
`
`VMware Technical Publications Glossary
`VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For
`definitions of terms as they are used in VMware technical documentation go to
`http://www.vmware.com/support/pubs.
`
`Document Feedback
`VMware welcomes your suggestions for improving our documentation. Send your feedback to
`docfeedback@vmware.com.
`
`VMware, Inc.
`
` 13
`
`

`

`vSphere Web Services API
`Programming Model
`
`2
`
`The vSphere Web Services API is implemented as a language-neutral Web service. The API is based on
`a remote procedure call mechanism that client applications use to access services and components on
`ESXi and vCenter Server systems.
`
`This chapter includes the following topics:
`vSphere Client-Server Architecture
`
`n
`
`n Web Services API as a Web Service
`
`n Access to Managed Objects
`
`n Access to vSphere Server Data
`
`vSphere Client-Server Architecture
`VMware vSphere client applications participate in a distributed architecture that uses an asynchronous
`communications model. This architecture is based on server-side managed objects, client-side managed
`object references, and data objects.
`
`n Managed objects exist on a vSphere server (ESX/ESXi or vCenter Server system). They represent
`vSphere services and components. Services include PropertyCollector, SearchIndex,
`PerformanceManager, and ViewManager. Components include inventory objects such as
`VirtualMachine, Datastore, and Folder.
`
`n Managed object references are client application references to server-side managed objects. Your
`client application uses ManagedObjectReference objects when it invokes operations on a server. A
`ManagedObjectReference is guaranteed to be unique and persistent during an object's lifetime. The
`reference persists after an object has moved within the inventory, across sessions, and across server
`restarts. If you remove an object, for example, a virtual machine, from the inventory, and then put it
`back, the reference changes.
`
`n Data objects contain information about managed objects. Your client application sends data objects to
`and receives data objects from a vSphere server. Examples are the different specification and
`capability objects such as VirtualMachineConfigSpec and HostCapability.
`
`VMware, Inc.
`
` 16
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Figure 2‑1 shows a vSphere server and client application. The client has a managed object reference to a
`virtual machine on the server, and a copy of the GuestInfo data object for the virtual machine. A client
`must maintain its copy of a data object because, depending on the type of client request, a vSphere
`server might send property data for a data object as a set of name-value pairs associated with a
`managed object reference. See the description of the ObjectContent data object in the vSphere API
`Reference.
`Figure 2‑1. vSphere Server and Client
`
`The VMware vSphere application model uses an asynchronous client-server communication model in
`most cases. Methods are nonblocking and return a reference to a Task managed object. For more
`information about the Task managed object, see Tasks and Scheduled Tasks.
`
`Web Services API as a Web Service
`The vSphere Web Services API is a language-neutral Web service that runs on ESXi and vCenter Server
`systems.
`
`The API complies with the Web Services Interoperability Organization (WS-I) Basic Profile 1.0. The WS-I
`Basic Profile 1.0 includes support for the following standards:
`
`n XML Schema 1.0
`
`n SOAP 1.1
`
`n WSDL 1.1
`
`For information about the WS-I Basic Profile 1.0, go to the Web Services Interoperability Organization
`(WS-I) Web site at http://www.ws-i.org.
`
`Web services support operations, which are the same as methods in other programming languages. The
`vSphere API Web service provides access to all operations necessary for monitoring and managing
`vSphere components, such as compute resources, virtual machines, networks, storage, and so on.
`
`WSDL Files and the Client-Side Proxy Interface
`The vSphere Web Services SDK provides a set of WSDL (Web Services Description Language) files that
`define the vSphere Web Services API. Web-services development tools such as JAX-WS wsimport, or
`Microsoft .NET wsdl.exe use these WSDL files to generate client-side proxy code (stubs).
`
`VMware, Inc.
`
` 17
`
`

`

`vSphere Web Services SDK Programming Guide
`
`The client proxy provides a language-specific interface proxy, for example, using Java or C#. The proxy
`facilitates remote method invocation, organization of object data, and other aspects of distributed, object-
`oriented, applications programming. Your client application calls proxy interface methods. The client proxy
`uses SOAP (Simple Object Access Protocol) to exchange WSDL messages with a vSphere server.
`Figure 2‑2 is a representation of a client application that uses the client proxy interface to call a method.
`The client proxy interface is based on the WSDL definitions.
`Figure 2‑2. Client-Server Communication Through a Client Proxy Interface
`
`To use the VMware client proxy interface, you must import the vSphere Web Services API client libraries
`in to your client application using the following Java and C# statements.
`
`C#
`
`Java
`
`using VimApi;
`
`import com.vmware.vim25.*;
`
`Important The vSphere Web Services SDK includes Java client-side proxy code that was generated
`using the JAX-WS toolkit. If the versions of Java and JAX-WS on your development platform are the
`same as those used to generate the proxy interface shipped in the SDK, you do not have to generate
`client-side proxy code from the WSDL. See the Developer’s Setup Guide for information about how to
`configure a development environment for the vSphere Web Services SDK.
`
`Network Access to the vSphere Web Service
`Your client application can use the vSphere Web Services API to communicate with vSphere servers over
`HTTPS (HTTP over an encrypted Secure Sockets Layer connection) at port 443. HTTPS is the default
`protocol.
`
`You can configure the server to support HTTP. Use HTTP access only for test or development
`environments, not for production. For information about how to configure the server to support HTTP
`access, see the vSphere Web Services SDK Developer’s Setup Guide.
`
`VMware, Inc.
`
` 18
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Language-Specific Classes and Methods
`The SOAP tools generate language-specific classes and methods that match the WSDL definitions. The
`tools also produce objects and methods that are not in the WSDL files.
`
`n Generated objects. The additional objects provide access to the vSphere Web Service to establish
`the client-server connection (VimServiceLocator, AppUtil) and declare the methods defined for
`the vSphere API (VimPortType, VimService).
`
`n Generated methods. The additional methods are accessor (getter) and mutator (setter) methods for
`properties. For Java, the method names are constructed by adding get and set prefixes to a
`property name, and changing the first character of the property name to upper case.
`
`The following table identifies client proxy definitions for the vSphere Web Services SDK WSDL.
`
`Element Access
`
`Java
`
`VimServiceLocator class
`
`C#
`
`AppUtil class
`
`Access to vSphere Web
`service (HTTPS/HTTP)
`
`Access to vSphere API
`methods
`
`VimPortType class
`
`VimService class
`
`Access to vSphere API
`properties
`
`getPropertyName and setPropertyName methods
`defined for data objects
`
`get and set methods defined for properties
`
`vSphere API data
`objects
`
`Data objects in the vSphere API (see the vSphere API Reference) defined as objects in the proxy
`interface
`
`The following code fragments show getter and setter method definitions for the
`AfterStartupTaskScheduler.minute property.
`
`Java
`
`public int getMinute() {
` return minute; }
`public void setMinute(int minute) {
` this.minute = minute; }
`
`C#
`
`public int minute {
` set; get; }
`
`You can extrapolate the getter and setter methods that are available in the client proxy interface from the
`vSphere API Reference. For example, the ScsiLun data object has a displayName property. For the
`Java API, you can use a setDisplayName method to assign a string value to the property, and obtain the
`string value by using the getDisplayName method. The vSphere Web Services SDK includes Java and
`C# sample code that illustrates how to use the proxy interfaces. See #unique_18.
`
`VMware, Inc.
`
` 19
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Mapping XML Data Types to Java and C# Data Types
`In this guide, the UML class and object diagrams use the primitive data type names such as string and
`integer, without the XML Schema definition namespace prefix (xsd:). The vSphere API Reference
`contains the complete data type name, such as xsd:string. The data types map to the primitive data
`types of the programming language used for the client application.
`
`The following table lists some of the more common XML primitive data type mappings.
`
`XML Schema
`
`xsd:base64binary
`
`xsd:boolean
`
`xsd:byte
`
`xsd:dateTime
`
`xsd:decimal
`
`xsd:double
`
`xsd:float
`
`xsd:int
`
`xsd:string
`
`Java
`
`byte[]
`
`boolean
`
`byte
`
`java.util.Calendar
`
`java.math.BigDecimal
`
`double
`
`float
`
`int
`
`java.lang.String
`
`.NET Data Type
`
`Byte[]
`
`Boolean
`
`SByte
`
`DateTime
`
`Decimal
`
`Double
`
`Single
`
`Int32
`
`String
`
`Access to Managed Objects
`Your client application obtains access to managed objects through the ServiceInstance managed
`object and its associated ServiceContent data object. The ServiceContent data object contains
`managed object references to services and manager entities, and to the root folder of the inventory.
`
`The ServiceInstance managed object is the root object of the inventory on both ESX/ESXi and vCenter
`Server systems. The server creates the ServiceInstance, and creates the manager entities that provide
`services in the virtual environment. Examples of manager entities are LicenseManager,
`PerformanceManager, and ViewManager.
`
`The ServiceInstance is the primary point of access to the server inventory. Your client application starts
`by connecting to a server and creating a reference to the ServiceInstance. After you have connected to
`the server, you can call the ServiceInstance.RetrieveServiceContent method to a
`ServiceContent data object. ServiceContent provides access to the vSphere managed object
`services. See Overview of a Java Sample Application for the Web Services SDK for an example of
`connecting to a server and using the ServiceInstance reference to retrieve the ServiceContent
`object.
`Figure 2‑3 shows the object model for the ServiceInstance and ServiceContent objects. The figure
`shows some of the ServiceContent managed object references and the target objects of the references.
`Each managed object reference identifies a specific managed object on the server with its type and a
`value. (The value property is an opaque string.)
`
`VMware, Inc.
`
` 20
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Figure 2‑3. ManagedObjectReference Data Object
`
`Access to vSphere Server Data
`To obtain information about the virtual infrastructure, you retrieve managed object properties. Managed
`object properties can be simple data types, such as integer or string data, or they can be complex types
`such as data objects that contain sets of properties.
`
`Obtaining Information from a Server
`With a reference to a managed object, you can obtain information about the state of the server-side
`inventory objects and populate client-side data objects based on the values. You can use one of the
`following approaches:
`
`n Use an accessor (getter) method. The client proxy interface provides accessor methods for each data
`object property. You can use these accessor methods to obtain the values of the object. See
`Language-Specific Classes and Methods for information about client proxy interface accessor
`methods.
`
`n Use a PropertyCollector to navigate to a selected point on the server and obtain values from
`specific properties. See #unique_28 for more information about PropertyCollector.
`
`VMware, Inc.
`
` 21
`
`

`

`vSphere Web Services SDK Programming Guide
`
`n Use the SearchIndex managed object to obtain a managed object reference to the managed entity
`of interest. The SearchIndex can return managed object references to specific managed entities—
`ComputeResource, Datacenter, Folder, HostSystem, ResourcePool, VirtualMachine—given an
`inventory path, IP address, or DNS name.
`
`Important You can use API methods to operate on managed objects in the vSphere inventory. A
`method that updates properties in one managed object may also update properties in other managed
`objects. The Server performs asynchronous updates to the inventory. There is no guarantee that the
`inventory will be completely updated when the method returns to the caller. Use the PropertyCollector
`method WaitForUpdatesEx to obtain property changes.
`
`Working with Data Structures
`Properties contain information about the server-side objects at a given point in time. The value of a
`property can be of one of the following types:
`
`n Simple data types, such as a string, boolean, or integer (or other numeric) data type. For example,
`the ManagedEntity managed object has a name property that takes a string value.
`
`n Arrays of simple data types or data objects. For example, a HostSystem managed object contains an
`array of managed object references (a type of data object) to virtual machines hosted by that physical
`machine. As another example, the SessionManager managed object has a sessionList property
`that is an array of UserSession data objects.
`
`n Enumerated types (enumeration, enum) of predefined values. The values can be a collection of
`simple data types or data objects. For example, a virtual machine's power state can be one of three
`possible string values—poweredOn, poweredOff, or suspended.
`
`The type of a property is often a string, but the property actually expects one of the values an
`enumeration encapsulates. For example, when you set VirtualMachineConfigSpec.guestid you
`can specify one of the elements of the VirtualMachineGuestOSIdentifier as a string.
`
`n Complex (or composite) data types. For example, the HostProfileConfigInfo object contains data
`objects, an array of data objects, and an array of strings.
`
`Accessing Property Values
`To use the composite data structures and arrays that contain Server data:
`
`n Use dot notation to access nested properties in composite data structures.
`
`n Cast unconstrained property values (xsd:anyType) to array types.
`
`n Use keys or index values as appropriate to access array values.
`
`VMware, Inc.
`
` 22
`
`

`

`vSphere Web Services SDK Programming Guide
`
`Nested Properties and Property Paths in Composite Data
`Structures
`vSphere Data objects can include properties that are defined as composite data types, such as data
`objects. The embedded data objects can also contain properties that are data objects. Properties can
`nest to several levels.
`
`For example, the following figure shows a UML class diagram of the VirtualMachine managed object,
`which has a runtime property that is defined as an xsd:dateTime data type. VirtualMachine also has
`a summary property that is a VirtualMachineSummary data object. The VirtualMachineSummary data
`object contains a config property that is a VirtualMachineConfigSummary data object.
`Figure 2‑4. VirtualMachine Managed Object and Nested Properties
`
`To refer to a nested property, use dot notation to separate the object names in the sequence that defines
`the path to the property. Your code must handle the type referenced at the end of the sequence.
`
`For example, you can compare the property referenced by the path summary.config.guestId (a string
`value) to the property refere