Returns virtual system summary information.
Syntax
uint32 GetSummaryInformation(
[in] CIM_VirtualSystemSettingData REF SettingData[],
[in] uint32 RequestedInformation[],
[out] Msvm_SummaryInformation SummaryInformation[]
);
Parameters
- SettingData [in]
-
An array of
CIM_VirtualSystemSettingData instances
that specifies the virtual machines and/or snapshots for which information is to be retrieved. If this
parameter is NULL, information for all virtual machines is retrieved.
- RequestedInformation [in]
-
An array of enumeration values (which correspond to the properties in the
Msvm_SummaryInformation class) that
specifies the data to retrieve for the virtual machines and/or snapshots specified in the
SettingData array. Values in the 0-99 range apply to both virtual machines and
snapshots. Values in the 100-199 range apply to virtual machines only, and will be ignored for elements of
SettingData which represent snapshots. Values in the 200-299 range apply to snapshots
only, and will be ignored for elements of SettingData which represent virtual
machines.
| Value | Meaning |
- Name
- 0
| This corresponds to the Name property of the
Msvm_SummaryInformation class.
|
- Element Name
- 1
| This corresponds to the ElementName property of the
Msvm_SummaryInformation class.
|
- Creation Time
- 2
| This corresponds to the CreationTime property of the
Msvm_SummaryInformation class.
|
- Notes
- 3
| This corresponds to the Notes property of the
Msvm_SummaryInformation class.
|
- Number of Processors
- 4
| This corresponds to the NumberOfProcessors property of the
Msvm_SummaryInformation class.
|
- Small Thumbnail Image (80x60)
- 5
| |
- MediumThumbnailImage (160x120)
- 6
| |
- LargeThumbnailImage (320x240)
- 7
| |
- EnabledState
- 100
| This corresponds to the EnabledState property of the
Msvm_SummaryInformation class.
|
- ProcessorLoad
- 101
| This corresponds to the ProcessorLoad property of the
Msvm_SummaryInformation class.
|
- ProcessorLoadHistory
- 102
| This corresponds to the ProcessorLoadHistory property of the
Msvm_SummaryInformation class.
|
- MemoryUsage
- 103
| This corresponds to the MemoryUsage property of the
Msvm_SummaryInformation class.
|
- Heartbeat
- 104
| This corresponds to the Heartbeat property of the
Msvm_SummaryInformation class.
|
- Uptime
- 105
| This corresponds to the UpTime property of the
Msvm_SummaryInformation class.
|
- GuestOperatingSystem
- 106
| This corresponds to the GuestOperatingSystem property of the
Msvm_SummaryInformation class.
|
- Snapshots
- 107
| This corresponds to the Snapshots property of the
Msvm_SummaryInformation class.
|
- AsynchronousTasks
- 108
| This corresponds to the AsynchronousTasks property of the
Msvm_SummaryInformation class.
|
- HealthState
- 109
| This corresponds to the HealthState property of the
Msvm_SummaryInformation class.
|
- OperationalStatus
- 110
| This corresponds to the OperationalStatus property of the
Msvm_SummaryInformation class.
Windows Server 2008: This value is not supported before Windows Server 2008 R2.
|
- StatusDescriptions
- 111
| This corresponds to the StatusDescriptions property of the
Msvm_SummaryInformation class.
Windows Server 2008: This value is not supported before Windows Server 2008 R2.
|
- SummaryInformation [out]
-
An array of
Msvm_SummaryInformation
instances containing the requested information for the virtual machines and/or snapshots specified in the
SettingData array. Properties not specified in the
RequestedInformation parameter will have a NULL
value.
Return Value
This method returns one of the following values.
- Completed with No Error (0)
- Method Parameters Checked - Job Started (4096)
- Failed (32768)
- Access Denied (32769)
- Not Supported (32770)
- Status is unknown (32771)
- Timeout (32772)
- Invalid parameter (32773)
- System is in used (32774)
- Invalid state for this operation (32775)
- Incorrect data type (32776)
- System is not available (32777)
- Out of memory (32778)
Remarks
Access to the
Msvm_VirtualSystemManagementService
class might be restricted by UAC Filtering. For more information, see
User Account Control and WMI.
Examples
The following C# sample displays summary information. The referenced utilities can be found in
Common Utilities for the
Virtualization Samples.
using System;
using System.Management;
namespace HyperVSamples
{
class GetSummaryInformationClass
{
ManagementObject virtualSystemService = null;
ManagementScope scope = null;
GetSummaryInformationClass()
{
scope = new ManagementScope(@"root\virtualization", null);
virtualSystemService = Utility.GetServiceObject(scope, "Msvm_VirtualSystemManagementService");
}
ManagementObject GetVirtualSystemSetting(string vmName)
{
ManagementObject virtualSystem = Utility.GetTargetComputer(vmName, scope);
ManagementObjectCollection virtualSystemSettings = virtualSystem.GetRelated
(
"Msvm_VirtualSystemSettingData",
"Msvm_SettingsDefineState",
null,
null,
"SettingData",
"ManagedElement",
false,
null
);
ManagementObject virtualSystemSetting = null;
foreach (ManagementObject instance in virtualSystemSettings)
{
virtualSystemSetting = instance;
break;
}
return virtualSystemSetting;
}
void GetSummaryInformation(ManagementObject[] virtualSystemSettings, UInt32[] requestedInformation)
{
ManagementBaseObject inParams = virtualSystemService.GetMethodParameters("GetSummaryInformation");
string[] settingPathes = new string[virtualSystemSettings.Length];
for (int i = 0; i < settingPathes.Length; ++i)
{
settingPathes[i] = virtualSystemSettings[i].Path.Path;
}
inParams["SettingData"] = settingPathes;
inParams["RequestedInformation"] = requestedInformation;
ManagementBaseObject outParams = virtualSystemService.InvokeMethod("GetSummaryInformation", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("Summary information was retrieved successfully.");
ManagementBaseObject[] summaryInformationArray = (ManagementBaseObject[])outParams["SummaryInformation"];
foreach (ManagementBaseObject summaryInformation in summaryInformationArray)
{
Console.WriteLine("\nVirtual System Summary Information:");
foreach (UInt32 requested in requestedInformation)
{
switch (requested)
{
case 0:
Console.WriteLine("\n\tName: {0}", summaryInformation["Name"].ToString());
break;
case 1:
Console.WriteLine("\tElement Name: {0}", summaryInformation["ElementName"].ToString());
break;
case 2:
Console.WriteLine("\tCreation Time: {0}", summaryInformation["CreationTime"].ToString());
break;
case 3:
Console.WriteLine("\tNotes: {0}", summaryInformation["Notes"].ToString());
break;
case 4:
Console.WriteLine("\tNumber of Processors: {0}", summaryInformation["NumberofProcessors"].ToString());
break;
}
}
}
}
else
{
Console.WriteLine("Failed to retrieve virtual system summary information");
}
inParams.Dispose();
outParams.Dispose();
}
void Close()
{
this.virtualSystemService.Dispose();
}
static void Main(string[] args)
{
if (args != null && (args.Length < 2 || args.Length > 6))
{
Console.WriteLine("GetSummaryInformation vmName value1 value2...");
Console.WriteLine("value:");
Console.WriteLine("\t0:Name");
Console.WriteLine("\t1:Element Name");
Console.WriteLine("\t2:Creation Time");
Console.WriteLine("\t3:Notes");
Console.WriteLine("\t4:Number of Processors");
Console.WriteLine("\nExample: GetSummaryInformation MyfirstVM 0 1 4");
return;
}
GetSummaryInformationClass getSummaryInfo = new GetSummaryInformationClass();
string vmName = args[0];
ManagementObject virtualSystemSetting = getSummaryInfo.GetVirtualSystemSetting(vmName);
ManagementObject[] settings = new ManagementObject[1];
settings[0] = virtualSystemSetting;
UInt32[] requestedInfo = new UInt32[args.Length - 1];
for (int i = 1; i < args.Length; ++i)
{
requestedInfo[i - 1] = UInt32.Parse(args[i]);
}
getSummaryInfo.GetSummaryInformation(settings, requestedInfo);
getSummaryInfo.Close();
virtualSystemSetting.Dispose();
}
}
}
The following VBScript sample displays summary information.
option explicit
dim objWMIService
dim managementService
dim fileSystem
const wmiSuccessful = 0
Main()
'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
dim computer, objArgs, vmName, vm, requestedInformation, vmSetting, vmSettings, i
set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")
computer = "."
set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")
set managementService = objWMIService.ExecQuery("select * from Msvm_VirtualSystemManagementService").ItemIndex(0)
set objArgs = WScript.Arguments
if WScript.Arguments.Count > 1 and WScript.Arguments.Count < 7 then
vmName = objArgs.Unnamed.Item(0)
redim requestedInformation(WScript.Arguments.Count - 2)
for i = 1 to WScript.Arguments.Count - 1
requestedInformation(i-1) = objArgs(i)
next
else
WScript.Echo "usage: cscript GetSummaryInformation.vbs vmName value1 value2..."
WScript.Echo "value:"
WScript.Echo "0:Name"
WScript.Echo "1:Element Name"
WScript.Echo "2:Creation Time"
WScript.Echo "3:Notes"
WScript.Echo "4:Number of Processors"
WScript.Quit(1)
end if
set vmSetting = GetVirtualSystemSetting(vmName)
vmSettings = Array(1)
vmSettings(0) = vmSetting.Path_.Path
if GetSummaryInformation(vmSettings, requestedInformation) then
WriteLog "Done"
WScript.Quit(0)
End if
WriteLog "GetSummaryInformation Failed."
WScript.Quit(1)
End Sub
'-----------------------------------------------------------------
' Retrieve Msvm_VirtualComputerSystem from base on its ElementName
'-----------------------------------------------------------------
Function GetComputerSystem(vmElementName)
On Error Resume Next
dim query
query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmElementName)
set GetComputerSystem = objWMIService.ExecQuery(query).ItemIndex(0)
if (Err.Number <> 0) then
WriteLog Format1("Err.Number: {0}", Err.Number)
WriteLog Format1("Err.Description:{0}",Err.Description)
WScript.Quit(1)
end if
End Function
'-----------------------------------------------------------------
' Retrieve Msvm_VirtualSystemSettingData Msvm_ComputerSystem object
'-----------------------------------------------------------------
Function GetVirtualSystemSetting(vmElementName)
dim query, computerSystem
set computerSystem = GetComputerSystem(vmElementName)
query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_VirtualSystemsettingData", computerSystem.Path_.Path)
set GetVirtualSystemSetting = objWMIService.ExecQuery(query).ItemIndex(0)
End Function
'-----------------------------------------------------------------
' GetSummaryInformation
'-----------------------------------------------------------------
Function GetSummaryInformation(settings, requestedInformation)
dim query, objInParam, objOutParams, summaryInformation, requested
set objInParam = managementService.Methods_("GetSummaryInformation").InParameters.SpawnInstance_()
objInParam.SettingData = settings
objInParam.RequestedInformation = requestedInformation
set objOutParams = managementService.ExecMethod_("GetSummaryInformation", objInParam)
if objOutParams.ReturnValue = wmiSuccessful then
GetSummaryInformation = true
for each summaryInformation in objOutParams.SummaryInformation
WriteLog "Virtual System Summary Information:"
for each requested in requestedInformation
select case requested
case 0:
WriteLog Format1("Name: {0}", summaryInformation.Name)
case 1:
WriteLog Format1("Element Name: {0}", summaryInformation.ElementName)
case 2:
WriteLog Format1("Creation Time: {0}", summaryInformation.CreationTime)
case 3:
WriteLog Format1("Notes: {0}", summaryInformation.Notes)
case 4:
WriteLog Format1("Number of Processors: {0}", summaryInformation.NumberofProcessors)
end select
next
next
else
WriteLog Format1("GetSummaryInformation failed with ReturnValue: {0}", objOutParams.ReturnValue)
end if
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
dim fileStream
set fileStream = fileSystem.OpenTextFile(".\GetVirtualSystemThumbnailImage.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formating functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
Format2 = Format1(myString, arg0)
Format2 = Replace(Format2, "{1}", arg1)
End Function
'------------------------------------------------------------------------------
' The string formating functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
Format1 = Replace(myString, "{0}", arg0)
End Function
Requirements
| Minimum supported client | None supported |
| Minimum supported server | Windows Server 2008 |
| MOF | WindowsVirtualization.mof |
| Namespace | \\.\Root\Virtualization |
See Also
- Msvm_VirtualSystemManagementService
- CIM_VirtualSystemSettingData
- Msvm_SummaryInformation
Send comments about this topic to Microsoft
Build date: 10/8/2009