Calling a WMI Method

  • Article

WMI supplies methods in the COM API and the scripting API to obtain information or manipulate objects in an enterprise system. For example, the WMI scripting method SWbemServices.ExecQuery queries for data. Providers also have methods defined in the classes they register. Examples are the Win32_LogicalDisk methods Chkdsk and ScheduleAutoChk supplied by the Win32 provider.

The following sections are discussed in this topic:

WMI Methods Compared to Provider Methods

By using WMI method calls combined with provider method calls, you can retrieve and manipulate information about your enterprise. For more information, see Calling a WMI Method and Calling a Provider Method.

The methods of the WMI scripting object SWbemObject have a special status because they can apply to any WMI data class. For more information, see Scripting with SWbemObject.

The following code example calls both WMI and provider methods.

The following WMI and provider methods are located in the Scripting API for WMI:

You can look up the code that may appear in "Return" in the Return Codes section for Win32_Service.

strComputer = "."
Set objWMIService = GetObject("winmgmts:" & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

Set colServices = objWMIService.ExecQuery ("Select * from Win32_Service where Name='Alerter'")
For Each objService in colServices
    Return = objService.StopService()
    If Return <> 0 Then
        Wscript.Echo "Failed " &VBNewLine & "Error code = " & Return 
    Else
       WScript.Echo "Succeeded"
    End If
Next


$colServices= Get-WmiObject -Class Win32_Service -Filter 'Name = &quot;Alerter&quot;'
foreach ($objService in $colServices)
{
    $objService.StopService()
}

Method-Calling Modes in WMI

The semisynchronous calling mode usually provides the best balance between security and performance.

For more information about each of the possible modes, see the following:

Synchronous Mode

Synchronous mode occurs when the program or scripts pauses until the method call returns a SWbemObjectSet collection object. WMI builds this collection in memory before returning the collection object to the calling program or script.

Synchronous mode can have an adverse effect of program or script performance on the computer running the program or script. For example, synchronously retrieving thousands of events from the event log can take a long time and use a lot of memory because WMI creates an object from each event and then puts those objects into a collection before passing the collection to the method.

You should only call methods that do not return large data sets in synchronous mode. The following SWbemServices methods can be safely called in synchronous mode:

Any SWbemServices methods without the word, "Async" in the name can be called in synchronous mode by setting the wbemFlagReturnWhenComplete value in the iFlags parameter.

Asynchronous Mode

Asynchronous mode occurs when the program or script continues to run after calling the method. WMI returns all objects from the method to a SWbemSink object as each object is created. The calling program or script must have an SWbemSink object and an SWbemSink.OnObjectReady event handler to process the returned objects. For more information about creating an event handler for asynchronous mode, see Receiving a WMI Event.

While this mode does not have the performance and resource penalty of synchronous mode, asynchronous mode can create serious security risks because the results stored in the SWbemSink object may not come from the calling program or script. WMI lowers the authentication level on the SWbemSink object until the method succeeds. For more information about how to mitigate these security risks, see Setting Security on an Asynchronous Call.

Methods appended with the word Async are methods for asynchronous mode. The following methods are asynchronous calls:

For more information about asynchronous mode, see:

Semisynchronous Mode

Semisynchronous mode is similar to asynchronous mode in that the program or script continues to run after calling the method. In semisynchronous mode, WMI retrieves the objects in the background as your script or program continues to run. WMI returns each object returned to the calling method right after the object is created.

Because WMI manages the object, semisynchronous mode is more secure than asynchronous mode. However, if you use semisynchronous mode with more than 1,000 instances, instance retrieval can monopolize the available resources, which can degrade the performance of the program or script and the computer using the program or script. Each object takes up the necessary resources until the memory is released.

To work around this condition, you can call the method with the iFlags parameter set with the wbemFlagForwardOnly and wbemFlagReturnImmediately flags to instruct WMI to return a forward-only SWbemObjectSet. A forward-only SWbemObjectSet eliminates the performance problem caused by a large data set by releasing the memory after the object is enumerated.

Any SWbemServices method that cannot be called in either synchronous or asynchronous mode is called in semisynchronous mode.

The following methods are called in semisynchronous mode:

For more information about semisynchronous mode, see Making a Semisynchronous Call with C++ and Making a Semisynchronous Call with VBScript.

Improving Enumeration Performance

Scripting with SWbemObject

WbemFlagEnum