Read-SCGuestInfo

Retrieves the value associated with a key in a guest operating system.

Description

The Read-SCGuestInfo cmdlet retrieves the value associated with a key (key/value pair) in a guest operating system.

For more information about Read-SCGuestInfo, type: "Get-Help Read-SCGuestInfo -online".

Parameters

KvpMap

Required? true
Accept Pipeline Input? false
Position? named 
Specifies a hashtable of key/value pairs (KVPs) corresponding to the KVP values exposed by Hyper-V.

JobVariable

Required? false
Accept Pipeline Input? false
Position? named 
Specifies that job progress is tracked and stored in the variable named by this parameter.

PROTipID

Required? false
Accept Pipeline Input? false
Position? named 
Specifies the ID of the PRO tip that triggered this action. This allows for auditing of PRO tips.

RunAsynchronously

Required? false
Accept Pipeline Input? false
Position? named 
Indicates that the job runs asynchronously so that control returns to the command shell immediately.

VM

Required? false
Accept Pipeline Input? false
Position? named 
Specifies a virtual machine object.

Key

Required? true
Accept Pipeline Input? false
Position? 1 
Specifies the key in a key/value pair (KVP).

JobVariable

Required? false
Accept Pipeline Input? false
Position? named 
Specifies that job progress is tracked and stored in the variable named by this parameter.

PROTipID

Required? false
Accept Pipeline Input? false
Position? named 
Specifies the ID of the PRO tip that triggered this action. This allows for auditing of PRO tips.

RunAsynchronously

Required? false
Accept Pipeline Input? false
Position? named 
Indicates that the job runs asynchronously so that control returns to the command shell immediately.

VM

Required? false
Accept Pipeline Input? false
Position? named 
Specifies a virtual machine object.

Examples

1: Get the IntegrationServicesVersion value for a specified key for a virtual machine. 
PS C:\> $VM = Get-SCVirtualMachine -Name "VM01"
PS C:\> Read-SCGuestInfo -VM $VM -Key "FullyQualifiedDomainName"

The first command gets the virtual machine object named $VM01 and stores the object in the $VM variable.

The second command returns the IntegrationServicesVersion key/value pair for virtual machine VM01.
2: Get the IntegrationServicesVersion value for a specified key for a virtual machine by using the pipeline operator. 
PS C:\> Get-SCVirtualMachine -Name "VM01" | Read-SCGuestInfo -Key IntegrationServicesVersion

This command returns the IntegrationServicesVersion key/value pair for virtual machine VM01.
3: Get multiple KVP values based on specified keys for a virtual machine. 
PS C:\> $ValuesMap = @{}
PS C:\> $ValuesMap.Add("NetworkAddressIPv4", $null)
PS C:\> $ValuesMap.Add("IntegrationServicesVersion", $null)
PS C:\> $VM = Get-SCVirtualMachine "VM02" 
PS C:\> Read-SCGuestInfo -VM $vm -KvpMap $ValuesMap

The first command creates an array named $ValuesMap.

The second and third commands add values to the $ValuesMap array.

The fourth command gets the virtual machine object named VM02 and stores the object in the $VM variable.

The last command returns the IntegrationServicesVersion and NetworkAddressIPv4 key/value pairs for virtual machine VM02.
4: Read multiple data types through a hashtable. 
PS C:\> $VM = Get-SCVirtualMachine -Name "VM03"
PS C:\> $ValuesMap = @{}
PS C:\> $ValuesMap.Add("NetworkAddressIPv4", $null)
PS C:\> Read-SCGuestInfo -VM $VM -KvpMap $ValuesMap
PS C:\> $ValuesMap.Add("NetworkAddressIPv6", $null)
PS C:\> Read-SCGuestInfo -VM $VM -KvpMap $ValuesMap
PS C:\> $ValuesMap2 = @{"NetworkAddressIPv4" = $null; "FullyQualifiedDomainName" = $null}
PS C:\> Read-SCGuestInfo -VM $VM -KvpMap $ValuesMap2

The first command gets the virtual machine object named VM03 and stores the object in the $VM variable.

The second command creates an array named $ValuesMap.

The third command adds NetworkAddressIPv4 to the $ValuesMap array. 

The fourth command gets the NetworkAddressIPv4 key/value pair for VM03.

The fifth command adds NetworkAddressIPv6 to the $ValuesMap array.

The sixth command gets the NetworkAddressIPv6 key/value pair for VM03.

The seventh command creates an array named $ValuesMap2 which contains NetworkAddressIPv4 and FullyQualifiedDomainName.

The last command returns the key/value pairs for NetworkAddressIPv4 and FullyQualifiedDomainName for VM03.
5: Read keys that do not exist. 
PS C:\> $VM = Get-SCVirtualMachine -Name "VM01"
PS C:\> $KeysDoNotExist = @{"o1ff1" = $null; "o1ff2" = $null; "o1ff3" = $null ; "o1ff4" = $null }
PS C:\> Read-SCGuestInfo -VM $VM -KVPMap $KeysDoNotExist 
PS C:\> $KeysDoNotExist = @{"off4" = $null; "o1ff2" = $null; "o1ff3" = $null ; "o1ff4" = $null }
PS C:\> Read-SCGuestInfo -VM $VM -KVPMap $KeysDoNotExist 
PS C:\> $KeysDoNotExist = @{"o1ff1" = $null; "o1ff2" = $null; "off4" = $null ; "o1ff4" = $null }
PS C:\> Read-SCGuestInfo -VM $VM -KVPMap $KeysDoNotExist

The first command gets the virtual machine object named VM01 and stores the object in the $VM variable.

The second, fourth, and sixth commands each create a set of keys that are null and stores the set in the $KeysDoNotExist variable.

The third, fifth, and seventh commands read the KVPMap in $KeysDoNotExist and displays the results to the user.

See Also