GetSummaryInformation method of the Msvm_VirtualSystemManagementService class

Returns virtual machine (VM) summary information.

Syntax

uint32 GetSummaryInformation(
  [in]  CIM_VirtualSystemSettingData REF SettingData[],
  [in]  uint32                           RequestedInformation[],
  [out] Msvm_SummaryInformation          SummaryInformation[]
);

Parameters

SettingData [in]

Type: CIM_VirtualSystemSettingData[]

An array of CIM_VirtualSystemSettingData instances that specifies the VMs and/or snapshots for which information is to be retrieved. If this parameter is NULL, information for all VMs is retrieved.

RequestedInformation [in]

Type: uint32[]

An array of enumeration values (which correspond to the properties in the Msvm_SummaryInformation class) that specifies the data to retrieve for the VMs and/or snapshots specified in the SettingData array. Values from 0 through 99 apply to both VMs and snapshots. Values from 100 through 199 apply to VMs only and are ignored for elements of SettingData that represent snapshots. Values from 200 through 299 are ignored.

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)

Medium Thumbnail Image (160x120) (6)

Large Thumbnail Image (320x240) (7)

AllocatedGPU (8)

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.

MemoryAvailable (112)

This corresponds to the MemoryAvailable property of the Msvm_SummaryInformation class.

Windows Server 2008 R2 and Windows Server 2008: This value is not supported before Windows Server 2008 R2 with SP1.

AvailableMemoryBuffer (113)

This corresponds to the AvailableMemoryBuffer property of the Msvm_SummaryInformation class.

Windows Server 2008 R2 and Windows Server 2008: This value is not supported before Windows Server 2008 R2 with SP1.

Return value

Type: uint32

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 use (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.

[!Important]
To function correctly, the following code must be run on the VM host server, and must be run with Administrator privileges.

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[] settingPaths = new string[virtualSystemSettings.Length];
            for (int i = 0; i < settingPaths.Length; ++i)
            {
                settingPaths[i] = virtualSystemSettings[i].Path.Path;
            }

            inParams["SettingData"] = settingPaths;
            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 &amp;&amp; (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.

[!Important]
To function correctly, the following code must be run on the VM host server, and must be run with Administrator privileges.

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 formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
    Format2 = Format1(myString, arg0)
    Format2 = Replace(Format2, "{1}", arg1)
End Function


'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
    Format1 = Replace(myString, "{0}", arg0)
End Function

Requirements

See also

Msvm_VirtualSystemManagementService

CIM_VirtualSystemSettingData

Msvm_SummaryInformation