TOPIC
    about_powercli_objects

SHORT DESCRIPTION
    Describes some importatant characteristics of the VMware PowerCLI objects.

LONG DESCRIPTION
    For their input and output, the VMware PowerCLI cmdlets use a set of .NET
    types that reside in the VMware.VimAutomation.ViCore.Types namespace. For
    example, the VMware.VimAutomation.ViCore.Types.V1.Inventory.VirtualMachine
    type describes virtual machine objects.  Each PowerCLI object represents a
    snapshot of the initial state of a server-side object by the time the
    PowerCLI object is created. Note that when the server-side object state
    changes, the state of the PowerCLI object is not automatically updated. To
    obtain the latest version, you have to retrieve the PowerCLI object from the
    server again. This behavior of the PowerCLI objects has some implications
    illustrated by the following example scenarios.

    SCENARIO 1:
    1. User A obtains an OSCustomizationSpec object (and stores it in a
    PowerShell variable).
    2. User B runs the Set-OSCustomizationSpec cmdlet to change the
    Administrator's Password in the OS customization specification.
    3. User A runs the Set-VM cmdlet providing the OSCustomizationSpec object
    obtained in step 1 as a parameter input.
    In result, User A unsuccessfully tries to perform the virtual machine OS
    customization, without knowing that the AdminPassword property of the
    OSCustomizationSpec server-side object has been changed by User B.

    SCENARIO 2:
    1. User A obtains a VirtualMachine object (and stores it in a PowerShell
    variable). The virtual machine is powered off.
    2. User B powers the virtual machine on.
    3. The PowerState property of the VirtualMachine object stored by User A is
    not updated and its value is PowerOff. User A tries to power on the virtual
    machine by using the Start-VM cmdlet.
    In result, Start-VM reports an error because the virtual machine is already
    powered on by User B. Another important case is working with Task objects.
    The Get-Task cmdlet returns a Task object and the state of this object is a
    snapshot of the initial server-side task state. Once you save the retrieved
    Task object in a PowerShell variable, its State property is never updated
    with the current state of the task on the server. To check if the
    server-side task has changed its state, run the Wait-Task cmdlet by using
    the Task object variable as a parameter.
    In all cases, when you run a cmdlet, it always retrieves and uses the latest
    version of the object properties for the specified parameters.

Properties Loaded On-Demand
    Some of the properties of the PowerCLI objects return other PowerCLI
    objects. Usually, when you first call such a property, it returns the output
    object and caches it for a faster return. Thus, every subsequent call to
    this property returns the cached object. However, every time when you
    retrieve an object through a cmdlet, the cached values of its properties are
    erased and the on-demand retrieving of the properties begins again.

Circular References
    To address new properties of objects returned by PowerCLI cmdlets, PowerCLI
    introduces circular references. For example, the VirtualMachine object has a
    property named VMResourceConfiguration that is of type
    VMResourceConfiguration. The VMResourceConfiguration type has a property
    named VM that is of type VirtualMachine.  In this case, the following
    expression is true:

    $vm.VMResourceConfiguration.VM.Uid -eq $vm.Uid

    The circular references should be taken into account when you use the
    Format-Custom cmdlet.  By default, the Format-Custom cmdlet makes a full
    traversal of an object and its references, and this might cause an infinite
    loop (for example, Get-VM | Format-Custom).

COPYRIGHT
    Copyright (C) VMware, Inc. All rights reserved. Protected by one or more
    U.S. Patents listed at http://www.vmware.com/go/patents.

