about_uid.help.txt
|
TOPIC
about_uid SHORT DESCRIPTION You can uniquely identify a PowerCLI object on a server or across multiple servers by specifying its Uid. LONG DESCRIPTION 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. 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'. 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. 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. EXAMPLES Example 1: GetParentUid(string uid) #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/" Example 2: GetParentUid(string uid, string parentKey) # If $uid is equal to: "/VIServer=powershell@vc41-ga.pc:443/VirtualMachine=VirtualMachine-vm-88/CDDrive=3001/" # Then the call below $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/" COPYRIGHT Copyright (c) Broadcom. All Rights Reserved. |