About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers  Aliases  Modules
 

UniqueidentifiersforPowerCLIobjects(Uid)

Uid

VMware.VimAutomation.Core
 
 

SHORT DESCRIPTION

 
You can uniquely identify a PowerCLI object on a server or across multiple servers by specifying its Uid.  
 
A Uid is a string that consists of one or more key-value pairs separated by a slash ("/"). The key and the value within a pair are separated by an equal sign ("=").   
 
For example, the Uid if a virtual CD Drive might be "/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/CDDrive=3001/". 
 
To retrieve the Uid of an object, use its Uid property. 
For example: 
	$vm = Get-VM -Name aaa 
	$vm.Uid 
 
To ease work with Uids, there is a global Powershell variable $UidUtil that provides methods for processing Uids. 
 
 

LONG DESCRIPTION

Although the name of an object is unique within a server, PowerCLI allows you to run cmdlets on multiple servers and this can lead to ambiguity. This means that the name or the short ID you have provided to a cmdlet might correspond to multiple objects on different servers. To avoid this, you can identify a PowerCLI object on a server or across multiple servers by specifying its Uid (unique identifier). The Uid contains information about the target server. 
 
A Uid is a string that consists of one or more key-value pairs separated by a slash ("/"). The key and the value within a pair are separated by an equal sign ("="). The first key-value pair represents the server connection. The objects which have no server-side analog and only live in the local memory start with "/Local=/".  
A Uid is said to be parent of another Uid if it can be obtained from the child Uid by removing one or more key-value pairs from the end of the child Uid. 
 

PROCESSING UIDS

 
The global variable $UidUtil provides the following methods for processing UIds: 
 
bool IsUid(string str)  -  Checks if the specified string is a valid Uid. 
 
string Append(string uid, string key, string value)  -  Appends the specified key and value to the specified Uid to form a child Uid. Any special characters will be encoded (in the same way as EncodeValue method). 
 
string GetKey(string uid)  -  Retrieves the key of the rightmost Uid element. 
 
string GetValue(string uid)  -  Retrieves the value of the rightmost Uid element. 
 
string GetValue(string uid, string key)  -  Retrieves the value of the leftmost Uid element which has the specified key. If the key is not present – returns $null. 
 
string EncodeValue(string plainString)  -  Encodes a string so that it can be used as a value of a Uid element (escapes delimiters). 
 
string DecodeValue(string encodedString)  -  Reverses the effect of Encode. 
 
string GetParentUid(string uid)  -  Returns the parent Uid of 'uid'.  
Example:  
	if $uid is equal to: 
	"/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/CDDrive=3001/" 
	 
	Then $UidUtil.GetParentUid($uid) will return:  
	"/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/" 
 
string GetParentUid(string uid, string parentKey)  -  Returns the shortest parent Uid of 'uid' which has a rightmost Uid element with the specified key. If the key is not present – returns $null. 
Example:  
	if $uid is equal to: 
	"/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/CDDrive=3001/" 
	 
	Then $UidUtil.GetParentUid($uid, "VirtualMachine") will return:  
	"/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/" 
	 
	And  $UidUtil.GetParentUid($uid, "VIServer") will return:  
	"/VIServer=powershell@vc41-ga.pc:443/" 
 
string GetConnectionUid(string uid)  -  Gets the Uid which represents the connection for this object. The connection Uid element is the first Uid element. 
 
bool IsOnConnection(string uid, string connectionKey, string connectionValue) - Reports whether uid belongs to the specified connection. 
 
void GetHelp() – Displays an about_ article with help information about the Uid concept and description of the methods’ functionality. 
 
The $UidUtil Powershell variable also exposes the following properties: 
 
string ElementDelimiter  -  The delimiter used to separate the different elements of a Uid 
string KeyValueDelimiter  -  The delimiter used to separate the key and the value of a Uid element 
 
 
Send feedback to docfeedback@vmware.com | Copyright (C) VMware, Inc. All rights reserved. Protected by one or more U.S. Patents listed at http://www.vmware.com/go/patents.