about_obn

Topic

Object-by-Name (OBN)

Short Description

A feature for specifying an object by its name. Instead of passing an object to a cmdlet parameter through a pipeline or by a variable, users can directly assign to the parameter the object name. A lot of PowerCLI cmdlets parameters support OBN.

Long Description

The Object-by-Name (OBN) selection is a feature for specifying an object by its name. Instead of passing an object to a cmdlet parameter through a pipeline or a variable, users can
directly assign to the parameter the object name. A lot of PowerCLI cmdlets parameters support OBN.

Example 1: The following three lines are interchangeable:

1. Remove-VM -VM "Win XP SP2"

2. Get-VM -Name "Win XP SP2" | Remove-VM

3. Remove-VM -VM (Get-VM -Name "Win XP SP2")

If one of the provided object names is not recognized, a non-terminating error is generated and the cmdlet runs ignoring the invalid name. This is called an "OBN failure".

Example 2: An "OBN Failure".

Set-VM -VM "VM1", "VM2", "VM3" -Server $server1, $server2 -MemoryGB 2

If the VM2 virtual machine does not exist on either of the specified servers, a non-terminating error is thrown and the command runs only on the VM1 and VM3 virtual machines.

OBN AND WILDCARDS

When specifying objects by name, you can use the standard PowerShell wildcards.

DETERMINING THE OBN SERVER LIST

You can use the Server parameter of a cmdlet to specify the servers from which to retrieve the objects specified by name. In such cases, the Server parameter can be set only if the parameter that takes an object name is specified.

Example 3: Using OBN and the cmdlets Server parameter.

Stop-VM -Server $svr1

To make the upper command work, you must provide at least one virtual machine name to the cmdlet VM parameter.

Stop-VM -Server $svr1 -VM "Win XP SP2"

If the Server parameter is not specified, OBN uses the servers associated with the objects passed as arguments to the other cmdlet parameters. If the arguments objects are associated with different servers, OBN is aborted for the current call and a non-terminating error is generated.

The Server parameter also supports OBN. You can specify servers either by their corresponding VIServer objects, or by their names.

Example 4: Using OBN with a server associated with the specified objects.

Move-VM -VM "Win XP SP2" -VMHost $myHost

The upper command will work only if the Win XP SP2 virtual machine and the $myHost host are associated with one and the same server. Otherwise, an error is generated.

If there are no servers specified by the Server parameter or associated with the provided objects, then the default server is used for OBN.

Example 5: Using OBN with the default server.

Move-VM -VM "Win XP SP2" -VMHost $myHost

If no server is associated with the specified objects, then the default server is used for OBN.

If a cmdlet parameter receives both managed objects and names, then the Server parameter applies only to the names and the managed objects are not filtered based on the servers.

If all cmdlet parameters receive only objects, and if a server list is specified, then the server list is ignored.

OBN ARGUMENT MULTIPLICITY AND PARAMETER MULTIPLICITY

After the object selection by name is performed, the returned objects are passed to the parameter together with the objects specified directly, if any, and the process continues.

Remove-VM -VM $vm1, $vm2, "Win XP SP2", $vm3, "linux*"

...is equivalent to...

Remove-VM -VM $vm1, $vm2, <the one or more objects named "Win XP SP2">, $vm3, <the zero or more objects, whose names start with "linux">

If a parameter receives multiple names specified by OBN as a part of its argument, and if the OBN for two of these names retrieves duplicate objects, these duplicates are not eliminated and the cmdlet works as if invoked with duplicate objects.

If the OBN selection returns no objects for a parameter that is specified as mandatory, or returns more than one object for a parameter that takes a single argument, an error is generated.

Send feedback to [email protected] | Copyright (C) VMware, Inc. All rights reserved. Protected by one or more U.S. Patents listed at http://www.vmware.com/go/patents.