WMI - Query
Declaration
<AMWMI WQL="text" RESULTDATASET="text" NAMESPACE="text (options)" HOST="text" DOMAIN="text" USERNAME="text" PASSWORD="text (encrypted)" />
Description
Connects to a local or remote computer and performs a WMI Query Language (WQL) query to retrieve Windows Management Instrumentation (WMI) supported information and populates a dataset with results. For convenience, this activity provides a WMI Query Builder, which is a built-in graphical interface that allows you to easily browse through the available WMI classes, objects and properties on the system and specify their values.
Practical usage
Normally used by Network Managers or System Administrators to monitor and control managed resources on a local or remote computer, thus, improving manageability of computers in a networked environment. For instance, a WQL Query task step can initially determine any issues and direct itself to perform proper activities to correct the problem before proceeding to other steps.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| WQL | Text | Yes | (Empty) | WQL="SELECT HandleCount FROM Win32_ProcessWHERE name='iexplore.exe'" |
The WMI query to execute. Click Query Builder to open the WMI Query Builder, a graphical interface that allows exploration of the full set of namespaces, classes, properties, and values available on a machine. Use this interface to navigate through the WMI set of objects and select the desired attributes. NOTE: By default, the WMI Query
Builder displays the local computer's namespaces, classes, objects
and properties. To display a remote computer's attributes, enable
the Remote computer parameter
in the Computer properties
and enter the remote machine's required credentials (that is, computer
name, username, domain and password).
|
| Namespace | Text | Yes | root\CIMV2 | NAMESPACE="root\CIMV2" | The
WMI namespace of where to execute the query. A WMI namespace contains
a hierarchy of classes and associations which define either a
machine's object or the relationship between two or more objects.
Click the drop-down combo box to select the desired namespace or enter
it manually in the provided combo-box. This parameter's default
value is root\CIMV2 (Common
Information Model Version 2) which is the most commonly used namespace. NOTE:
If a namespace is specified from the WMI Query Builder, the selected
namespace overwrites any value currently entered in this parameter. |
| Create and populate dataset | Text | Yes | (Empty) | RESULTDATASET="theWMIdata" | The
name of the dataset to create and populate with query results. NOTE: The value and amount of
returned datasets will differ depending on the WMI query executed.
|
Computer
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Local computer | --- | --- | --- | --- | If
selected, specifies queries are performed on the local
machine (selected
by default). NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Remote computer | --- | --- | --- | --- | If
selected, specifies queries are performed on a remote
machine (disabled by default). When this parameter is selected, the Local
computer parameter becomes disabled. NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Computer | Text | Yes, if Remote computer selected | (Empty) |
|
The computer name or IP address of the remote (host) machine to query. This parameter is required if the Remote computer parameter is selected. |
| Domain | Text | Yes, if Remote computer selected | (Empty) | DOMAIN="netauto" | The domain name of the remote machine. On Win2000, WinXP and Server2003, if a domain name is specified, it is automatically appended to the username and separated with an @ symbol (for example, username@domain.com). This parameter is required if the Remote computer parameter is selected. |
| Username | Text | Yes, if Remote computer selected | (Empty) | USERNAME="remoteUser" | A valid username used to log onto the remote machine. This parameter is required if the Remote computer parameter is selected. |
| Password | Text | Yes, if Remote computer selected | (Empty) | PASSWORD="encrypted" | A valid password used to log onto the remote machine. This parameter is required if the Remote computer parameter is selected. |
Examples
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Example 1
This sample task performs a WMI query that returns the number of handles used by all running instances of Internet Explorer on the local computer. Results are populated into DatasetName.HandleCount.
<AMWMI RESULTDATASET="DatasetName" NAMESPACE="root\CIMV2">SELECT HandleCount FROM Win32_Process WHERE name='iexplore.exe'</AMWMI>Example 2
This sample task performs a WMI query that returns the number of processes on the local computer which use more than 10 threads. Results are populated into DatasetName.ThreadCount.
<AMWMI RESULTDATASET="DatasetName" NAMESPACE="root\CIMV2">SELECT ThreadCount FROM Win32_Process WHERE ThreadCount>10</AMWMI>