Operating System

Windows Management Instrumentation Scripting

White Paper

Abstract This paper presents an overview of the WindowsManagement Instrumentation (WMI) Scripting API. The Windows Management Instrumentation is an implementation of the Distributed Management Task Forces (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 980526399 USA 0100

Contents
Introduction............................................................................................1 Introduction............................................................................................1
Windows Management Instrumentation Technology Windows Management Instrumentation Technology 1 1

WMI Architecture Overview...................................................................2 WMI Architecture Overview...................................................................2 Common Information Model (CIM)........................................................5 Common Information Model (CIM)........................................................5 WMI Script Usage...................................................................................6 WMI Script Usage...................................................................................6
Advantages of Using WMI Scripting Advantages of Using WMI Scripting Examples Examples List all Processes Running on the Local System List all Services Running on the System on Host Products1 Display the Routing Tables Contents on an SNMP Device Display Information about a Remote Computer System Products1 Listen for NT Event Log Events on the Local System Enable an Interface on an SNMP Device Terminate all Copies of the Notepad Process on Host Rogue Enable DHCP on the Local System 7 7 7 7 7 7 8 8 8 9 9 9

Restart all Services which are Dependent on the NetDDE Service on Host Products1 10 Change the Name of a Disk Use of the Asynchronous API and Scripting in Web Pages 10 10

WMI Scripting Interface........................................................................12 WMI Scripting Interface........................................................................12

Scripting Object Model Scripting Object Model Features Features WMI Scripting Model Objects WMI Scripting Model Objects SWbemLocator Object SWbemSink Object SWbemServices Object SWbemEventSource Object SWbemObject Path Object SWbemNamedValue Object SWbemNamedValueSet Collection SWbemObject SWbemObjectSet Collection SWbemLastError Object SWbemQualifier Object SWbemQualifierSet Collection SWbemProperty Object SWbemPropertySet Collection SWbemMethod Object SWbemMethod Collection SWbemSecurity Object 12 12 13 13 14 14 14 14 15 15 16 17 17 17 19 19 19 20 20 21 21 22 22

Conclusion............................................................................................22 Conclusion............................................................................................22 For More Information...........................................................................23 For More Information...........................................................................23

Introduction

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 Technology The 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 machinereadable 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. The WMI technology provides: Access to monitor, command, and control any managed object through

Windows 2000 Server White Paper 1

WMI Architecture Overview

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, wellarchitected 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 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

Windows 2000 Server White Paper 2

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.

a n ( W

a g e m e n t A p p l i c a M I C o n s u m e r )

t i o

I M

O ( W

j e c t i n M g

M m

a n t )

e R

r C ( CI M I M O M ) e p o s i t o r y

r o

v i d
3

.e .r s .
d

r o

v i d

r s

Windows 2000 Server White Paper

M S

a n a g e y s t e m

M S

a n a g e y s t e m

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. Event Log Provider. Provides access to data and event notifications from the Windows 2000 Event Log.

Windows 2000 Server White Paper 4

Common Information Model (CIM)

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 objectoriented 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. 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).

Windows 2000 Server White Paper 5

WMI Script Usage

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 hostone 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 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.

Windows 2000 Server White Paper 6

Advantages of Using WMI Scripting Using 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.

Examples This 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.
for each Process in GetObject("winmgmts: {impersonationLevel=impersonate}").InstancesOf ("Win32_process") WScript.Echo Process.Name Next

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.

Windows 2000 Server White Paper 7

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

Display the Routing Tables 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_ComputerSy stem= ServerName") WScript.Echo System.Caption WScript.Echo System.PrimaryOwnerName WScript.Echo System.Domain WScript.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.

Windows 2000 Server White Paper 8

on error resume next set locator = CreateObject("WbemScripting.SWbemLocator") 'Access to the NT event log requires the security privilege locator.Security_.Privileges.AddAsString "SeSecurityPrivilege" set events = locator.ConnectServer().ExecNotificationQuery _ ("select * from __instancecreationevent where targetinstance isa 'Win32_NTLogEvent'") if err <> 0 then WScript.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.Source Exit Do elseif NTEvent.TargetInstance.Message <> Empty then WScript.Echo NTEvent.TargetInstance.Message else Wscript.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.

Windows 2000 Server White Paper 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" Then Service.StartService () wscript.echo service.name End IF Next

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.

Windows 2000 Server White Paper 10

Synchronous example:
<HTML> <HEAD> <TITLE>WBEM VBScript Example</TITLE> <SCRIPT LANGUAGE="VBScript"> Sub window_onload const impersonation = 3 Set Locator = CreateObject("WbemScripting.SWbemLocator") Set Service = Locator.ConnectServer() Service.Security_.ImpersonationLevel=impersonation Set Process = Service.Get("Win32_Service.Name=""Winmgmt""") document.all.info.innerText = Process.DisplayName end 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"> <!-Sub Document_OnClick const impersonate = 3 Set Service = Locator.ConnectServer() Service.Security_.ImpersonationLevel = impersonate Service.GetAsync mysink,"Win32_Service.Name=""Winmgmt""" end sub

--> </SCRIPT> </HEAD> <BODY> The name of the service is <SPAN ID="info"> unknown </SPAN>. <OBJECT ID="Locator" CLASSID="CLSID:76A64158-CB41-11D1-8B0200600806D9B6"></OBJECT> <OBJECT ID="mysink" CLASSID="CLSID:75718C9A-F029-11d1-A1AC00C04FB6C223"></OBJECT> </BODY> </HTML>

Windows 2000 Server White Paper 11

WMI Scripting Interface

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 Model Figure 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.

Windows 2000 Server White Paper 12

E v e n t S in k

L o c a to r

N a m e d V a lu e Set

E v e n t S o u rce

S e r v ic e

N a m e d V a lu e

S e c u r it y

C IM O b je c t C o lle c t io n

L a st E rro r

C IM O b je c t

O b je c t P a t h

P r o p e r ty C o lle c t io n

Q u a lif ie r C o lle c t io n

M e th o d C o lle c t io n

P r o p e r ty

Q u a lif ie r

M e th o d

Figure 2. Principal objects in WMI scripting model

Features The 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

Windows 2000 Server White Paper 13

representation of a Moniker is called a Display Name. With the WMI scripting API, you can create SWbemObject and SWbemServices 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 Objects The 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.

Windows 2000 Server White Paper 14

OnCompleted. This is called when an asynchronous call completes. 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).

Windows 2000 Server White Paper 15

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). 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:

1

SetAsClass. Coerces the path to address a class. SetAsSingleton. Coerces the path to address a singleton instance

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.

Windows 2000 Server White Paper 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.

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)).

Windows 2000 Server White Paper 17

The SWbemObject supports the following automation properties4: 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 readwrite). 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.

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

method name.
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.

Windows 2000 Server White Paper 18

SpawnDerivedClass_. Creates a subclass object. SpawnInstance_. Creates an instance object. CompareTo_. Compares with another object. 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

Windows 2000 Server White Paper 19

Read-only. Value (DEFAULT). The Qualifier value. Type is Variant, and access is Read-write. 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

Windows 2000 Server White Paper 20

access is Read-only9. CIMtype. CIM type of property (not including the "array"-ness). Type is WbemCimtypeEnum, and access is Read-only. 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.

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.

10

The Add and Remove methods are not supported on an Instance. By Read-Only is meant that the automation property is read-only, but not necessarily the contents of that

11

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

Windows 2000 Server White Paper 21

Conclusion

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. 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.

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.

Windows 2000 Server White Paper 22

For More Information

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.

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.

Windows 2000 Server White Paper 23