about_obn
TOPIC
about_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.
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, 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, the default server is
used for OBN. If a cmdlet parameter receives both managed objects and names,
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, 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.
COPYRIGHT
Copyright (C) VMware, Inc. All rights reserved. Protected by one or more
U.S. Patents listed at http://www.vmware.com/go/patents.
Copyright © VMware, Inc. All rights reserved.