SWbemServices object

You can use the methods of an SWbemServices object to perform operations against a namespace on either a local host or a remote host. This object cannot be created by the VBScript CreateObject call.

Members

The SWbemServices object has these types of members:

• Methods
• Properties

Methods

The SWbemServices object has these methods.

Properties

The SWbemServices object has these properties.

Remarks

The methods can be called in either the synchronous mode, the asynchronous mode, or the semisynchronous mode. For more information see Calling a Method.

Overview

SWbemServices serves two primary roles. First, the SWbemServices object represents an authenticated connection to a WMI namespace on a target computer. Second, SWbemServices is the Automation object you use to retrieve WMI-managed resources. You can obtain a reference to an SWbemServices object in either of two ways:

• As demonstrated in most of the WMI scripts presented thus far, you can use the VBScript GetObject function in combination with the WMI moniker "winmgmts:". The following example is the simplest form of a WMI connection. The example connects to the default namespace (typically "Root\CIMv2") on the local computer:

  Set objSWbemServices = GetObject("winmgmts:")

• You can also use the SWbemLocator object ConnectServer method to obtain a reference to an SWbemServices object.

After you obtain a reference to an SWbemServices object, you use the object reference to call 1 of 18 methods available using SWbemServices. SWbemServices can return one of three different WMI scripting library objects (SWbemObjectSet, SWbemObject, or SWbemEventSource), depending on the method you call. Knowing the type of object each method returns will help you determine the next step your script must take. For example, if you get back an SWbemObjectSet, you must enumerate the collection to access each SWbemObject in the collection. If you get back an SWbemObject, you can immediately access the object methods and properties without enumerating the collection first.

Modes of Operation

SWbemServices supports three modes of operation: synchronous, asynchronous, and semisynchronous.

• Synchronous. In synchronous mode, your script blocks (pauses) until the SWbemServices method completes. Not only does your script wait, but in cases in which WMI retrieves instances of managed resources, WMI builds the entire SWbemObjectSet in memory before the first byte of data is returned to the calling script. This can have an adverse effect on the script performance and on the computer running the script. For example, synchronously retrieving thousands of events from the Windows Event Logs can take a long time and use a lot of memory. For these reasons, synchronous operations are not recommended except for the three methods (Delete, ExecMethod, and Get) that are synchronous by default. These methods do not return large data sets, so semisynchronous operation is not required.

• Asynchronous. In asynchronous mode, your script calls one of the nine asynchronous methods and returns immediately. That is, as soon as the asynchronous method is called, your script resumes running the next line of code. To use an asynchronous method, your script must first create an SWbemSink object and a special subroutine called an event handler. WMI performs the asynchronous operation and notifies the script by calling the event handler subroutine when the operation is complete.

• Semisynchronous. Semisynchronous mode is a compromise between synchronous and asynchronous. Semisynchronous operations offer better performance than synchronous operations, yet they do not require the extra knowledge and scripting steps necessary to handle asynchronous operations. This is the default operation type for most WMI queries.

  In semisynchronous mode, your script calls one of the six data retrieval methods and returns immediately. WMI retrieves the managed resources in the background as your script continues to run. As the resources are retrieved, they are immediately returned to your script by way of an SWbemObjectSet. You can begin to access the managed resources without waiting for the entire collection to be assembled.

  There is a caveat to semisynchronous operations when you are working with managed resources that have many instances (many meaning greater than 1,000), such as CIM_DataFile and Win32_NTLogEvent. The caveat is a result of how WMI handles instances of managed resources. For each instance of a managed resource, WMI creates and caches an SWbemObject object. When a large number of instances exist for a managed resource, instance retrieval can monopolize available resources, reducing the performance of both the script and the computer.

  To work around the problem, you can optimize semisynchronous method calls using the wbemFlagForwardOnly flag. The wbemFlagForwardOnly flag, combined with the wbemFlagReturnImmediately flag (the default semisynchronous flag), tells WMI to return a forward-only SWbemObjectSet, which eliminates the large data set performance problem. However, using the wbemFlagForwardOnly flag comes with a cost. A forward-only SWbemObjectSet can be enumerated only once. After each SWbemObject in a forward-only SWbemObjectSet is accessed, the memory allocated to the instance is released.

With the exception of the Delete, ExecMethod, Get, and nine asynchronous methods, semisynchronous is the default and recommended mode of operation.

Commonly-used Methods

The methods most often used in system administration scripts are InstancesOf, ExecQuery, Get, and ExecNotificationQuery. Although often used, InstancesOf is not necessarily the recommended way to retrieve information (although it is arguably the easiest way).

Requirements

See also

Scripting API Objects

Calling a Method