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
The SWbemServices object has these methods.
| Method | Description |
|---|---|
| AssociatorsOf | Retrieves the instances of managed resources that are associated with a specified resource through one or more association classes. You provide the object path for the originating endpoint, and AssociatorsOf returns the managed resources at the opposite endpoint. The AssociatorsOf method performs the same function that the "ASSOCIATORS OF" WQL query performs. |
| AssociatorsOfAsync | Asynchronously returns a collection of objects (classes or instances) that are associated with a specified object. |
| Delete | Deletes an instance of a managed resource (or a class definition from the CIM repository). |
| DeleteAsync | Asynchronously deletes the class or instance that is specified in the object path. |
| ExecMethod | Provides an alternative way to execute a method defined by a managed resource class definition. Primarily used in situations in which the scripting language does not support out parameters. For example, JScript does not support out parameters. |
| ExecMethodAsync | Asynchronously executes a method that is exported by a method provider. |
| ExecNotificationQuery | Executes an event subscription query to receive events. An event subscription query is a query that defines a change to the managed environment that you want to monitor. When the change occurs, the WMI infrastructure delivers an event describing the change to the calling script. |
| ExecNotificationQueryAsync | Asynchronously executes a query to receive events. |
| ExecQuery | Executes a query to retrieve a collection of instances of WMI-managed resources (or class definitions). ExecQuery can be used to retrieve a filtered collection of instances that match criteria you define in the query passed to ExecQuery. |
| ExecQueryAsync | Asynchronously executes a query to retrieve objects. |
| Get | Retrieves a single instance of a managed resource (or class definition) based on an object path. |
| GetAsync | Asynchronously retrieves an object, that is either a class definition or an instance, based on the object path. |
| InstancesOf | Retrieves all the instances of a managed resource based on a class name. By default, InstancesOf performs a deep retrieval. That is, InstancesOf retrieves the instances of the resource identified by the class name passed to the method and also retrieves all the instances of all the resources that are subclasses (defined beneath) of the target class. |
| InstancesOfAsync | Asynchronously returns the instances of a specified class according to the user-specified selection criteria. |
| ReferencesTo | Returns all of the associations that reference a specified resource. The best way to understand ReferencesTo is to compare it with the AssociatorsOf method. AssociatorsOf returns the dynamic resources that are at the opposite end of an association. ReferencesTo returns the association itself. The ReferencesTo method performs the same function that the "REFERENCES OF" WQL query performs. |
| ReferencesToAsync | Asynchronously returns a collection of all association classes or instances that refer to a specific class or instance. |
| SubclassesOf | Retrieves all the subclasses of a specified class from the CIM repository. |
| SubclassesOfAsync | Asynchronously returns a collection of subclasses for a specified class. |
Properties
The SWbemServices object has these properties.
| Property | Access type | Description |
|---|---|---|
| Security_ |
Read-only |
Used to get or set the security settings for an SWbemServices object. |
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
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows Vista |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Type library |
|
| DLL |
|
| CLSID |
CLSID_SWbemServices |
| IID |
IID_ISWbemServices |