wmiscript

Operating System

Windows Management Instrumentation Scripting

White Paper

Abstract

This paper presents an overview of the Windows Management Instrumentation (WMI) Scripting API.

The Windows Management Instrumentation is an implementation of the Distributed Management Task

Force’s (DMTF) Web-Based Enterprise Management (WBEM) initiative, which provides standards for

accessing and sharing management information in an enterprise environment.

© 2000 Microsoft Corporation. All rights reserved.The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.Microsoft, Active Directory, ActiveX, JScript, Visual Basic, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation.Other product and company names mentioned herein may be the trademarks of their respective owners.Microsoft Corporation • One Microsoft Way • Redmond, WA 98052-6399 • USA0100

Introduction............................................................................................1

Windows Management Instrumentation Technology 1

WMI Architecture Overview...................................................................3

Common Information Model (CIm)........................................................6

WMI Script Usage...................................................................................7

Advantages of Using WMI Scripting 7

Examples 8

List all Processes Running on the Local System 8

List all Services Running on the System on Host Products1 8

Display the Routing Table’s Contents on an SNMP Device 8

Display Information about a Remote Computer System Products1 8

Listen for NT Event Log Events on the Local System 9

Enable an Interface on an SNMP Device 9

Terminate all Copies of the Notepad Process on Host Rogue 9

Enable DHCP on the Local System 9

Restart all Services which are Dependent on the NetDDE Service on Host

Products1 10

Change the Name of a Disk 10

Use of the Asynchronous API and Scripting in Web Pages 10

WMI Scripting Interface........................................................................13

Scripting Object Model 13

Features 14

WMI Scripting Model Objects 15

SWbemLocator Object 15

SWbemSink Object 15

SWbemServices Object 16

SWbemEventSource Object 16

SWbemObject Path Object 16

SWbemNamedValue Object 18

Contents

SWbemNamedValueSet Collection 18

SWbemObject 18

SWbemObjectSet Collection 20

SWbemLastError Object 20

SWbemQualifier Object 20

SWbemQualifierSet Collection 21

SWbemProperty Object 21

SWbemPropertySet Collection 22

SWbemMethod Object 22

SWbemMethod Collection 23

SWbemSecurity Object 23

Conclusion............................................................................................24

For More Information..............................................................................25

The Windows® Management Instrumentation (WMI) technology is the

Microsoft® implementation of the Distributed Management Task Force (DMTF)

Web-Based Enterprise Management (WBEM) initiative that extends the

Common Information Model (CIM) to represent management objects in

Windows-based management environments. The Common Information Model,

also a DMTF standard, is an extensible data model for logically organizing

management objects in a consistent, unified manner in a managed

environment.

Based on the Common Information Model, WBEM is a DMTF initiative and

technology that establishes management infrastructure standards and provides

a standardized way to access information from various hardware and software

management systems in an enterprise environment. Using WBEM standards,

developers can create tools and technologies that reduce the complexity and

costs of enterprise management. By providing such standards, WBEM

contributes to industry-wide efforts to lower total cost of ownership (TCO). TCO

refers to the administrative costs associated with computer hardware and

software purchases, deployment and configuration, hardware and software

updates, training, maintenance, and technical support.

WBEM provides a point of integration through which data from management

sources can be accessed, and it complements and extends existing

management protocols and instrumentation such as Simple Network

Management Protocol (SNMP), Desktop Management Interface (DMI), and

Common Management Information Protocol (CMIP).

The WBEM initiative results from the cooperative efforts of Microsoft, BMC

Software, Cisco Systems, Compaq Computer, and Intel, as well as many other

member companies active in the DMTF.

This paper presents a brief overview of WMI (the Microsoft implementation of

the WBEM standard) and its architecture, including detailed information about

the WMI provider interfaces and aspects of programming WMI providers.

Windows Management Instrumentation TechnologyThe Windows Management Instrumentation (WMI) technology is a

management infrastructure that supports the syntax of CIM, the Managed

Object Format (MOF), and a common programming interface. The MOF syntax

defines the structure and contents of the CIM schema in human and machine-

readable form. Windows Management Instrumentation offers a powerful set of

services, including query-based information retrieval and event notification.

These services and the management data are accessed through a Component

Object Model (COM) programming interface. The WMI scripting interface also

provides scripting support.

Windows 2000 Server White Paper

1

Introduction

The WMI technology provides:

Access to monitor, command, and control any managed object through

a common, unifying set of interfaces, regardless of the underlying

instrumentation mechanism. WMI is an access mechanism.

A consistent model of Windows 2000 operating system operation,

configuration, and status.

A COM Application Programming Interface (API) that supplies a single

point of access for all management information.

Interoperability with other Windows 2000 management services. This

approach can simplify the process of creating integrated, well-

architected management solutions.

A flexible, extensible architecture. Developers can extend the

information model to cover new devices, applications, and so on, by

writing code modules called WMI providers, described later in this

document.

Extensions to the Windows Driver Model (WDM) to capture

instrumentation data and events from device drivers and kernel-side

components.

A powerful event architecture. This allows management information

changes to be identified, aggregated, compared, and associated with

other management information. These changes can also be forwarded

to local or remote management applications.

A rich query language that enables detailed queries of the information

model.

A scriptable API which developers can use to create management

applications. The scripting API supports several languages, including

Microsoft Visual Basic®; Visual Basic for Applications; Visual Basic,

Scripting Edition (VBSript); Microsoft JScript® development software.

Besides VBScript and JScript, developers can use any scripting

language implementation that supports Microsoft ActiveX® scripting

technologies with this API (for example, a Perl scripting engine). In

addition, you can use the Windows Script Host or Microsoft Internet

Explorer to write scripts using this interface. Windows Script Host, like

Internet Explorer, serves as a controller engine of ActiveX scripting

engines. Windows Script Host supports scripts written in VBScript, and

JScript.

The WMI technology architecture consists of the following:

A management infrastructure. This includes the CIM Object

Manager, which provides applications with uniform access to


2

WMI Architecture Overview

management data and a central storage area for management data

called the CIM Object Manager repository.

WMI Providers. These function as intermediaries between the CIM

Object Manager and managed objects. Using the WMI APIs, providers

supply the CIM Object Manager with data from managed objects,

handle requests on behalf of management applications, and generate

event notifications.

The management infrastructure consists of CIM Object Manager and the CIM

Object Manager repository. Applications depend on the Object Manager to

handle the interface between management applications and data providers.

WMI facilitates these communications by providing a common programming

interface to Windows management services using COM. This COM API

supplies event notification and query processing services, and can be used in

several programming language environments such as C and C++. The CIM

Object Manager repository holds the CIM and extension schemas, and data

information or data source details. CIM Object Manager uses the schema data

in this repository when servicing requests from management applications for

managed objects.

Managed objects are either physical or logical enterprise components that are

modeled using CIM. For example, a managed object can be hardware such as

a cable, or software such as a database application. Management applications

can access managed objects through CIM Object Manager.

Management applications are applications or Windows 2000 services that use

or process information originating from managed objects. Management

applications can access managed object information by making a request to

CIM Object Manager through one of the methods in the WMI API.

WMI providers are standard COM and Distributed Component Object Model

(DCOM) servers that function as mediators between managed objects and the

CIM Object Manager. If the CIM Object Manager receives a request from a

management application for data that is not available from the CIM Object

Manager repository or for event notifications that are not supported by the CIM

Object Manager, it forwards the request to a WMI provider. Providers supply

data and event notifications for managed objects that are specific to their

particular domain. Figure 1 below illustrates the three layer model WMI uses,

which consists of providers, the CIM Object Manager, and consumers of WMI

information.


3

Figure 1.WMI Model

To implement a provider, you should use one of the following supported server

types:

Microsoft Windows 2000 services, local or remote.

Standard executables (.exe files), local or remote.

In-process dynamic-link libraries (DLLs).

Note that local or remote Windows 2000 services and standard executables are

recommended server types.

WMI ships with built-in providers (or standard providers) that supply data from

sources such as the system registry. The built-in providers include:

Active Directory Provider. Acts as a gateway to all the information

stored in the Active Directory™ service. Allows information from both

WMI and Active Directory to be accessed using a single API.

Windows Installer Provider. Allows complete control of Windows

Installer and installation of software through WMI. Also supplies

information about any application installed with Windows Installer.

Performance Counter Provider. Exposes the raw performance

counter information used to compute the performance values shown in

the System Monitor tool. Any performance counters installed on a

system will automatically be visible through this provider. Supported by

Windows 2000.

Registry Provider. Allows Registry keys to be created, read, and

written. WMI events can be generated when specified Registry keys

are modified

SNMP Provider. Acts as a gateway to systems and devices that use

the Simple Network Management Protocol (SNMP) for management.

SNMP MIB object variables can be read and written. SNMP traps can

be automatically mapped to WMI events.


4

Event Log Provider. Provides access to data and event notifications

from the Windows 2000 Event Log.

Win32 Provider. Provides information about the operating system,

computer system, peripheral devices, file systems, and security

information.

WDM Provider. Supplies low level Windows Driver Model driver

information for user input devices, storage devices, network interfaces,

and communications ports.

View Provider. Allows new aggregated classes to be built up from

existing classes. Source classes can be filtered for only the information

of interest, information from multiple classes can be combined into a

single class and data from multiple machines can be aggregated into a

single view.

The WMI technology also provides support for third party custom providers.

Custom providers can be used to service requests related to managed objects

that are environment-specific. Providers typically use the MOF language to

define and create classes. Providers use the WMI API to access the CIM

Object Manager repository, and to respond to CIM Object Manager requests

made initially by applications.

Additional technical papers on WMI are available on the Microsoft Web site.

The next sections present an overview of the WMI Scripting interface and

includes samples.

All management information exposed through WMI is described using the

Common Information Model (CIM). CIM, created by the Distributed

Management Task Force (http://www.dmtf.org), is a standard, unified object-

oriented framework for describing physical and logical objects in a managed

environment. To provide a common framework, CIM defines a series of objects

with respect to a basic set of classes, classifications, and associations.

CIM includes the following information models:

A core model. Incorporates notions applicable to all management

domains.

Common models. Incorporate notions common to specific

management domains, independent of particular technologies or

implementations. Common domains include systems, applications,

devices, users, and networks. These models provide a basis for the

development of management applications, and include a set of base

classes for extension into technology-specific areas.


5

Common Information Model (CIM)

http://www.dmtf.org/

http://www.microsoft.com/windows/server/technical/management/default.asp

Extension models. These represent technology-specific extensions of

the common models. These models are specific to environments, such

as operating systems (for example, UNIX or the Microsoft Windows

operating system).

Some Notes about CIM:

It provides the ability to encapsulate and classify managed objects by

building on abstract Classes to define physical or logical management

elements. For example a managed object can be a cable, a software

application or a running process.

Relationships between objects can be modeled using the concept of an

Association, which are themselves described as CIM classes. For

example, Windows NT® service dependencies can be modeled in this

way.

Classes are made of up Properties and Methods. For example, a class

to model a hard disk might have a property that represents the free

space available on the disk, and a method to format the disk.

Actual management information is surfaced as Instances of CIM

Classes. For example, there might be three instances of the Class that

represents a disk on my host—one representing my hard drive, one my

floppy drive, and the other my CDROM drive.

Classes and Instances live in Namespaces. A Namespace represents a

logical scope for classes and instances.

The WMI Scripting API can be used for the following purposes:

Server, workstation, and system management. Write scripts to

manage computers, services, drivers, devices, file systems, DNS and

DHCP servers, and Windows NT Event Logs. You can also create

scripts for network configuration tasks. For example, you can create

scripts to start and stop system services, list and monitor system

drivers, list records in the Windows NT Event Logs, and so on.

Security and user management. Write scripts to list account

information pertaining to a specific domain user or domain group, or to

list directory permissions, and so on.

Network management. Write a script to list the configuration of

network adapter cards on a specific computer.

Printer management. Write scripts to monitor for printer status or

printer tray empty events on a specific printer, or to display the


6

WMI Script Usage

configuration of all locally connected printers, and so on.

System health monitoring. Create scripts to monitor and display the

Windows NT Event Log entries added to the local event log files, or to

monitor the Windows NT System Monitor log files.

Advantages of Using WMI ScriptingUsing WMI for scripting provides the following advantages:

Data-driven approach based on the Common Information Model. A

single interface is used for manipulating disparate management

information, and applications can be isolated from the complexity of

various data sources.

Rich coverage of system, network, device, and application information.

The WMI SDK includes Providers for Win32® API, SNMP, Registry,

Performance Monitor, Windows 2000 Event Log, and ADSI. Third-party

custom Providers can be created to cover vendor-specific

instrumentation (for system, applications, devices, and so on). In

addition, Providers will be available for the Microsoft Windows Installer,

SQL Server™ Administration, COM+ Catalog, and SNA Server.

Extensible Providers instrumentation. The WMI SDK provides tools,

samples, and an extensible Provider architecture called the framework.

The development of new Providers is supported by the industry.

Uses existing technologies. The WMI scripting API uses many of the

built-in features of VBScript for automation such as collections,

exception information-passing, and so on.

Exposure of CIM properties and methods directly as automation

properties and methods, making it easy to write scripts in a natural and

intuitive style.

ExamplesThis section highlights some VBScript examples of WMI Scripting API usage.

List all Processes Running on the Local System

The following code segment illustrates the use of enumeration, direct access to

a CIM property (in this case the Name property of an instance of the CIM class

Win32_Service) as if it were an automation property, and local access.


7

for each Process in GetObject("winmgmts:{impersonationLevel=impersonate}").InstancesOf ("Win32_process")

WScript.Echo Process.NameNext

List all Services Running on the System on Host Products1

The following code segment illustrates the use of enumeration, direct CIM

property access, and remote access to Windows 2000 system.

for each Service in GetObject("winmgmts:{impersonationLevel=impersonate}!//ServerName").InstancesOf ("Win32_service")

WScript.Echo Service.DisplayNameNext

Display the Routing Table’s Contents on an SNMP Device

The following code segment illustrates the use of enumeration, direct CIM

property access, and remote access to an SNMP device.

for each RoutingEntry in GetObject("winmgmts://./snmp/routerA").InstancesOf (" SNMP_RFC1213_MIB_ipRouteTable")

WScript.Echo RoutingEntry.ipRouteDest, RoutingEntry.ipRouteNextHop, RoutingEntry.ipRouteType

Next

Display Information about a Remote Computer System Products1

The following code segment illustrates the use of Get specified object on a

remote machine, and direct CIM property access.

Set System = GetObject("winmgmts:{impersonationLevel=impersonate}!//ServerName/root/cimv2:Win32_ComputerSystem= “”ServerName””")WScript.Echo System.CaptionWScript.Echo System.PrimaryOwnerNameWScript.Echo System.DomainWScript.Echo System.SystemType

Listen for NT Event Log Events on the Local System

The following code segment illustrates the use of registration of a temporary

event consumer on a specified event filter, and direct CIMproperty access.


8

on error resume nextset locator = CreateObject("WbemScripting.SWbemLocator")

'Access to the NT event log requires the security privilegelocator.Security_.Privileges.AddAsString "SeSecurityPrivilege"

set events = locator.ConnectServer().ExecNotificationQuery _ ("select * from __instancecreationevent where targetinstance isa

'Win32_NTLogEvent'")

if err <> 0 thenWScript.Echo Err.Description, Err.Number, Err.Source

end if

' Note this next call will wait indefinitely - a timeout can be specified

WScript.Echo "Waiting for NT Events..."WScript.Echo ""

do set NTEvent = events.nextevent if err <> 0 then

WScript.Echo Err.Number, Err.Description, Err.SourceExit Do

elseif NTEvent.TargetInstance.Message <> Empty thenWScript.Echo NTEvent.TargetInstance.Message

elseWscript.Echo "Event received, but it did not contain a

message."end if

loop

WScript.Echo "finished"

Enable an Interface on an SNMP Device

The following code segment illustrates the use of Get specified remote SNMP

device (object), Get specified instance (index 10 in interface table), and Set

specified property (ifAdminStatus) to specified value (up).

Set Interface = GetObject(“winmgmts://./snmp/routerA:SNMP_RFC1213_MIB_ifTable.ifIndex=10")Interface.ifAdminStatus = "up"Interface.Put_ ()

Terminate all Copies of the Notepad Process on Host Rogue

The following code segment illustrates the use of Query, and direct CIM

method execution (as if it were an automation method).

for each Process in GetObject("winmgmts:{impersonationLevel=impersonate}!//ServerName").ExecQuery ("select * from Win32_Process where Name='notepad.exe'")

Process.Terminate (0)Next

Enable DHCP on the Local System

The following code segment illustrates the use of Get specified object, direct

CIM property access, and update of class changes to Windows Management.


9

Set Adapter = GetObject("winmgmts:Win32_NetworkAdapterConfiguration=1")

RetVal = Adapter.EnableDHCP()

if RetVal = 0 then WScript.Echo "DHCP Enabled"

else WScript.Echo "DHCP enable failed"

end if

Restart all Services which are Dependent on the NetDDE Service on Host

Products1

The following code segment illustrates the use of enumeration, association

traversal, and method invocation.

For Each Service in GetObject("winmgmts:{impersonationLevel=impersonate}!//./root/cimv2").ExecQuery ("Associators of {Win32_service.Name=""NetDDE""} Where AssocClass = Win32_DependentService")

If Service.State = "Stopped" ThenService.StartService () wscript.echo service.name

End IFNext

Change the Name of a Disk

The following code segment illustrates the use of instance modification.

set disk = GetObject ("winmgmts:{impersonationLevel=impersonate}!//./root/cimv2:Win32_LogicalDisk=""C:""")disk.VolumeName = "My C Drive"disk.Put_

Use of the Asynchronous API and Scripting in Web Pages

The following two examples illustrate the use of the asynchronous API and

scripting in a web page.


10

Synchronous example:

<HTML><HEAD><TITLE>WBEM VBScript Example</TITLE><SCRIPT LANGUAGE="VBScript">

Sub window_onloadconst impersonation = 3Set Locator = CreateObject("WbemScripting.SWbemLocator")Set Service = Locator.ConnectServer()Service.Security_.ImpersonationLevel=impersonationSet Process = Service.Get("Win32_Service.Name=""Winmgmt""")document.all.info.innerText = Process.DisplayNameend sub

</SCRIPT></HEAD><BODY>The name of the service is <SPAN ID="info">unknown</SPAN>.</BODY></HTML>

Asynchronous example.

<HTML><HEAD><TITLE>WBEM VBScript Example</TITLE>

<SCRIPT FOR="mysink" EVENT="OnCompleted(hResult, ErrorObject, Context)" LANGUAGE="VBScript">

alert("Completed")</SCRIPT>

<SCRIPT FOR="mysink" EVENT="OnObjectReady(Winmgmt, Context)" LANGUAGE="VBScript">

document.all.info.innerText = Winmgmt.DisplayName</SCRIPT>

<SCRIPT LANGUAGE="VBScript"> </SCRIPT></HEAD><BODY>The name of the service is <SPAN ID="info">unknown</SPAN>.<OBJECT ID="Locator" CLASSID="CLSID:76A64158-CB41-11D1-8B02-00600806D9B6"></OBJECT><OBJECT ID="mysink" CLASSID="CLSID:75718C9A-F029-11d1-A1AC-00C04FB6C223"></OBJECT></BODY></HTML>


11

The next sections present an overview of the WMI scripting interfaces.

The WMI SDK documents the scripting API that you can use to create scripts

and Visual Basic-based applications to interact with the CIM Object Manager. It

supports the following languages:

Microsoft Visual Basic.

Visual Basic for Applications.

Visual Basic, Scripting Edition.

Microsoft JScript.

In addition, you can also use any scripting language implementation that

supports Microsoft's ActiveScripting technologies with this API (such as a Perl

scripting engine).

Scripting Object ModelFigure 2 below illustrates the principal objects and their relationships within the

WMI Scripting Object Model. The boxes represent objects in the scripting

model. The boxes with a heavy border represent the objects that the API can

create directly, while shaded boxes represent automation collection objects. An

arrow from object A to object B signifies that A can obtain B by calling A using

the scripting API relationship. A collection is a standard automation concept

that provides a uniform interface to a set of objects over which iteration can be

performed. To manipulate collections using a specific programming language,

you use the native features of that language.


12

WMI Scripting Interface

Figure 2. Principal objects in WMI scripting model

FeaturesThe WMI SDK supports the following features to leverage the capabilities of the

scripting languages:

Object Creation. You can create objects directly using the specified

ProgID for these WMI interfaces: SWbemLocator,

SWbemObjectPath, SWbemLastError, SwbemSink and

SWbemNamedValueSet. The method for creating objects depends on

the programming language you use. The WMI Scripting model objects

are described in the next section.

Collections. Several standard Automation collection interfaces are

provided in the WMI API. You can manipulate collections by using the

native features of each scripting language.

Monikers. A Moniker is a COM standard mechanism for encapsulating

the location and binding of another COM object. The textual

representation of a Moniker is called a Display Name. With the WMI

scripting API, you can create SWbemObject and SWbemServices


13

Event Sink

Event Source

Named ValueSet

Locator

MethodCollection

CIM ObjectCollection

Named ValueService

Security

QualifierCollection

Object PathCIM Object

PropertyCollection

Property MethodQualifier

Last Error

objects in a concise manner using the concept of Moniker Display

Names.

Direct Access. This feature allows you to access the CIM properties of

a CIM or WMI class or instance directly on an SWbemObject, rather

than through the Properties_y collection of that object. You can also

execute methods on that object in the native style of the programming

language, rather than using the SWbemServices.ExecMethod or

SWbemObject.ExecMethod_ calls. In other words, the API allows you

to treat CIM methods and properties as if they were automation

methods properties of SWbemObject.

Error Handling. If an error occurs as a result of a call to the CIM

Object Manager through the WMI scripting API, the error information

can be accessed using the native error mechanisms of the scripting

language.

Optional Parameters. Many of the WMI Scripting API parameters are

optional and provide default values, allowing you to omit them when

appropriate to streamline development.

WMI Scripting Model ObjectsThe next sections describe the scripting model objects. The SWbemLocator

object is created using conventional methods for creating coclasses; other

objects can be created using Moniker display names.

SWbemLocator Object

This object represents a WMI locator. You can create this object directly as a

coclass. It supports one method, ConnectServer, which you use to obtain a

SWbemServices object. It has no properties.

SWbemSink Object

This object represents a sink for WMI events; it is used for asynchronous API

calls. You can create this object directly as a coclass. It supports the Cancel

method, which cancels all outstanding asynchronous calls bound to this object

instance.

The sink supports the following events (callback methods, not to be confused

with WMI events):

OnObjectReady. This is called when a CIM Object is returned from an

asynchronous call.

OnCompleted. This is called when an asynchronous call completes.


14

OnProgress. This is called to report the progress of an asynchronous

call.

OnPut. This is called when a CIM Object is saved following an

asynchronous Put call.

SWbemServices Object

This object represents an authenticated connection to a namespace. It has a

single automation property called Security_, of type SWbemSecurity, which

returns the SWbemSecurity object for this SWbemServices object. It has

Read and Write access.

The object supports the following automation methods, in both synchronous

and asynchronous form:

Get. Retrieves a CIM Class or Instance.

Delete. Deletes a CIM Class or Instance.

SubclassesOf. Enumerates subclasses of a CIM Class.

InstancesOf. Enumerates instances of a CIM Class.

ExecQuery. Executes a WQL query.

ExecNotificationQuery. Executes a WQL notification query, and

returns an SWbemEventSource.

ExecMethod. Executes a method on a CIM instance or class.

AssociatorsOf. Retrieves associators of a CIM instance or class.

ReferencesTo. Retrieves references to a CIM instance or class.

SWbemEventSource Object

This object represents a source of events obtained from WMI; it is returned by

the ExecNotificationQuery method of the SWbemServices object. It supports

the Security_ automation property, which returns the SWbemSecurity object

for this SWbemEvent Source object.

It supports the NextEvent method, which is used to get the next event from the

source (or timeout).

SWbemObject Path Object

This is a helper object that can be used to construct WMI object paths (without

the user being required to know the details of the Object Path syntax).


15

This object supports the following automation properties:

Path (DEFAULT1). Represents the full WMI path. Type is BSTR, and

access is Read and Write.

RelPath. The relative (to namespace) path. Type is BSTR, and access

is Read and Write.

Server. The server name. Type is BSTR, and access is Read and

Write.

Namespace. The namespace path. Type is BSTR, and access is Read

and Write.

ParentNamespace. The parent namespace. Type is BSTR, and

access is Read only.

DisplayName. The moniker-style display name. Type is BSTR, and

access is Read and Write.

Class. The name of the class. Type is BSTR, and access is Read and

Write.

IsClass. Indicates whether the path addresses a class. Type is

Boolean, and access is Read only.

IsSingleton. Indicates whether the path addresses a singleton

instance. Type is Boolean, and access is Read only.

Key. The set of key value bindings for this path. Type is

SWbemNamedValueSet2, and access is Read only.

The SWbemObject Path Object supports the following methods:

SetAsClass. Coerces the path to address a class.

SetAsSingleton. Coerces the path to address a singleton instance

1 Throughout this paper, the term DEFAULT is applied to a property or method to indicate that it is the

Dispatch Default property/method on an automation object. This means that the property name can be

omitted. For example, the following VBScript fragment would output the value of the Path property of an

Object Path:

WScript.Echo MyObjectPath

where MyObjectPath is an Object Path object.

2 This object is immutable, but can be cloned to provide a mutable copy.


16

SWbemNamedValue Object

This object is used to model a named value, which is a combination of a name

and a VARIANT value. Named values are collected in a

SWbemNamedValueSet collection object.

The SWbemNamedValue object supports the following automation properties:

Name. The name of the value. Type is BSTR, and access is Read only.

Value. The value. Type is VARIANT, and access is Read and Write.

SWbemNamedValueSet Collection

This is a collection object composed of SWbemNamedValue objects. It is used

to model a collection of named values that may be passed as additional

information to a method of the SWbemServices, SwbemObject, or

SWbemLocator objects.

SWbemNamedValueSet supports the collection properties Count and

_NewEnum. It also supports the standard collection methods, Add, Item, and

Remove. The Item implementation allows the use of the value name as the

indexing mechanism for the collection3.

SWbemNamedValueSet also supports the DeleteAll method, which removes

all named values from the collection.

SWbemObject

This object is used to represent a single CIM instance or class.

CIM properties (those which would appear in a MOF, but not WMI system

properties) and methods are exposed in one of two ways:

Directly via the “dot” notation as automation methods and properties of

this interface. This is extremely convenient for scripts written to

manipulate specific CIM objects.

Indirectly via the property and method collections available from this

object. This is required for schema browser type scripts which deal with

objects generically.

The SWbemObject supports the following automation properties4:

3 It is possible to use WbemNamedValueSet(“foo”) in VB or VBScript as a concise means of referring

to the element of the WbemNamedValueSet whose name is “foo” (that is, as a shorthand for

WbemNamedValueSet.Item(“foo”)).

4 These property names use a trailing "_" character to avoid the possibility of a name clash with a CIM

method name.


17

Derivation_. An array of class names (possibly empty) describing the

derivation hierarchy. The first, lowest-index, member of the array is the

__SUPERCLASS, and the last is the __DYNASTY5. Type is

SAFEARRAY of VARIANT, and access is Read only6.

Path_. Contains location and naming information for the CIM Object7.

Type is SWbemObjectPath object, and access is Read only (with the

single exception that the Class property of the object path is read-

write).

Qualifiers_. Represents a collection of object-level qualifiers. Type is

SWbemQualifierSet, and access is Read only.

Properties_. Represents a collection of object properties. Type is

SWbemPropertySet, and access is Read only.

Methods_. Represents a collection of object methods. Type is

SWbemMethodSet, and access is Read only.

Security_. Returns the Security object for this object. Type is

SWbemSecurity.

Note that system properties are exposed in the scripting API as automation

properties of the CIM Object, rather than true CIM properties. In addition, the

__PROPERTY_COUNT system property is exposed as the standard collection

Count property of the SWbemPropertySet Collection object.

The SWbemObject supports the following methods8 (those methods marked

with an asterisk have additional asynchronous equivalents):

Clone_. Creates a copy of this object.

GetObjectText_. Retrieves MOF representation of this object.

SpawnDerivedClass_. Creates a subclass object.

SpawnInstance_. Creates an instance object.

CompareTo_. Compares with another object.

5 This single automation property encompasses 3 system properties exposed in the C++ COM API:

__DERIVATION, __DYNASTY and __SUPERCLASS.

6 By Read-Only is meant that the automation property is read-only, but not necessarily the contents of that

property, in the case that the property represents a collection or Object.

7 This single automation property encompasses 6 system properties exposed in the C++ COM API:

__GENUS, __CLASS, __SERVER, __NAMESPACE, __RELPATH and __PATH. Following the paradigm of

that API, only the Class automation property of this object is writable.

8 These names use a trailing "_" character to avoid the possibility of a name clash with a CIM method name.


18

Put_*. Submits the object to CIM Object Manager.

Delete_*. Deletes the object from CIM Object Manager.

ExecMethod_*. Executes a method on the object.

Instances_*. Enumerates instances of the object (object must be a

class).

Subclasses_*. Enumerates subclasses of the object (object must be a

class).

Associators_*. Enumerates associators of the object.

References_*. Enumerates references to the object.

SWbemObjectSet Collection

This is a collection object that is composed of SWbemObjects. It is used to

model the result set associated with an enumeration or query.

SWbemObjectSet supports the Collection properties _NewEnum and Count.

It also supports the Collection method Item, where the index supplied is the

relative path of the object.

SWbemObjectSet supports the Security_ property, which returns the

SWbemSecurity object for the Collection.

SWbemObjectSet does not support the optional Collection methods Add and

Remove. This object also supports the WMI Clone method.

SWbemLastError Object

This object (which is an SWbemObject) must be created directly and may be

used to return the last WMI extended error object (if any) generated on the

current thread. The object has read-once semantics (meaning it is cleared after

reading).

The SWbemLastError object is used to provide similar functionality to the

GetLastError call in the Win32 API.

SWbemQualifier Object

This object represents a qualifier. It has the following automation properties:

Name. Represents the Qualifier name. Type is BSTR, and access is

Read-only.

Value (DEFAULT). The Qualifier value. Type is Variant, and access is

Read-write.


19

IsLocal. Specifies whether the qualifier is local to the owning object, or

has been propagated. Type is BOOL, and access is Read-only.

PropagatesToSubclass. Controls the propagation behavior to

subclasses. Type is BOOL, and access is Read-write.

PropagatesToInstance. Controls the propagation behavior to

instances. Type is BOOL, and access is Read-write.

IsOverridable. Determines whether the Qualifier may be overridden

when propagated. Type is BOOL, and access is Read-write.

Origin. Represents the originating class name. Type is BSTR, and

access is Read-only.

SWbemQualifierSet Collection

This is a collection object that is composed of SWbemQualifier Objects. It

represents the set of qualifiers attached to a CIM element (class, instance,

property, method, or method parameter).

SWbemQualifierSet supports the standard Collection methods (Add, Item,

and Remove), and the standard Collection properties (Count and

_NewEnum). The Item implementation allows the use of the qualifier name as

the indexing mechanism for the collection.

SWbemProperty Object

This object represents a property. It has the following automation properties:

Name. Represents the Property name. Type is BSTR, and access is

Read only.

Value (DEFAULT). The Property value. Type is Variant, and access is

Read and Write.

IsLocal. Specifies whether the property is local to the owning object, or

has been propagated. Type is BOOL, and access is Read only.

Origin. The name of the originating class. Type is BSTR, and access is

Read-only

Qualifiers_. Represents Property qualifiers. Type is Collection, and

access is Read-only9.

CIMtype. CIM type of property (not including the "array"-ness). Type is

WbemCimtypeEnum, and access is Read-only.


property, in the case that the property represents a collection.


20

IsArray. Determines whether the property is an array type. Type is

BOOL, and access is Read-only.

The Qualifiers_ collection is a SWbemQualifierSet Collection object (the

trailing underscore has been retained for consistency with the SWbemObject

naming of the analogous automation property).

SWbemPropertySet Collection

This is a collection object composed of SWbemProperty Objects. It represents

the set of properties attached to a CIM element (class or instance).

The SWbemPropertySet object supports the standard Collection methods

(Add, Item, and Remove), and the standard Collection properties (Count and

_NewEnum) 10. The Item implementation allows the use of the property name

as the indexing mechanism for the collection.

SWbemMethod Object

This object represents a method. It has the following automation properties:

Name. Represents to the Method name. Type is BSTR, and access is

Read only.

Origin. The name of the originating class. Type is BSTR, and access is

Read only.

Qualifiers_. Represents Method qualifiers. Type is SWbemQualifier,

and access is Read only11.

InParameters. The In parameters definition. Type is SWbemObject,

and access is Read only.

OutParameters. The Out parameters definition. Type is

SWbemObject, and access is Read only.

SWbemMethod Collection

This is a collection object that is composed of SWbemMethod Objects. It

represents the set of methods attached to a CIM element (class or instance)12.

10 The Add and Remove methods are not supported on an Instance.


property, in the case that the property represents a collection.

12 Due to a feature of the underlying WMI COM API, this collection is always empty on an instance. In

addition, the Add method is not supported on an instance.


21

SWbemMethodSet supports the standard Collection method Item. The Item

implementation allows the use of the method name as the indexing mechanism

for the collection. The Add and Remove methods are not supported, as this is

essentially a Read only collection.

The standard Collection properties _NewEnum and Count are also supported.

SWbemSecurity Object

This object represents the DCOM security attributes on an object; it is exposed

as a property on any object in the API that supports remote access to Windows

Management services. The following object types support remote access:

CIM Object (SWbemObject)

CIM Object Collection (SWbemObjectSet)

Services (SWbemServices)

Event Source (SWbemEventSource)

All of the above objects surface the SWbemSecurity object as a property

called Security_.

The Security object supports the following automation properties with Read

and Write access:

ImpersonationLevel

AuthenticationLevel

In each case, the value of the property is an enumeration type, whose

members correspond precisely to the values supported by the standard DCOM

security method IClientSecurity::SetBlanket.

Based on industry standards and using a data-centric approach, WMI provides

a single point of access for manipulating disparate management information in

a managed environment. WMI uses existing technologies and provides tools,

samples, and an extensible Provider architecture that developers can use as a

basis for building vendor-specific management solutions for network, systems,

devices, and so on.

With the WMI Scripting interface, you can create scripts for management tasks

related to networks, systems, servers and workstations, security and users,

system health monitoring, printers, and more.


22

Conclusion

For the latest information on Windows 2000 Server, check out our Web site at

http://www.microsoft.com//windows2000 and the Windows 2000/NT Forum at

http://computingcentral.msn.com/topics/windowsnt.

For more information on WMI, see http://www.microsoft.com/management/wmi.

For more information on scripting, see http://msdn.microsoft.com/scripting/.

For more information on the WBEM initiative and for information about the

efforts of the DMTF, see http://www.dmtf.org.


23

For More Information

http://www.dmtf.org/

http://msdn.microsoft.com/scripting/

http://www.microsoft.com/management/wmi

http://computingcentral.msn.com/topics/windowsnt

http://www.microsoft.com//windows2000%20

wmiscript

Documents