WMI Monikers

Windows Management Instrumentation (WMI) provides two distinct mechanisms you can use to connect to WMI and mine system information in your WMI scripts: the WMI Scripting Library's SWbemLocator object, and the WMI moniker, "winmgmts:". The moniker is considered more powerful because it lets you use just one line of code to concisely describe a WMI object or collection of WMI objects to retrieve and manage. However, with power comes the difficulty of constructing complex WMI moniker strings. Let's decipher the components you can use to construct WMI monikers and look at a few best practices for writing WMI scripts that use WMI monikers.

This column assumes a basic knowledge of WMI and WMI terminology. To get quickly up to speed on WMI, read the articles in "Related Articles in Previous Issues."

A Moniker Is ...
Before I dive into the individual components you can use to build WMI moniker strings, I should define exactly what a moniker is because it's an unfamiliar term to many systems administrators. The term moniker comes from the COM programming discipline. In simple terms, a moniker is a string, also called a display name, that provides location and identity information about an object that you want to instantiate in your script. From a pure COM point of view, a moniker is just another programmatic identifier (ProgID) that maps to a class identifier (CLSID) that in turn points to the DLL containing the target automation object. As with all automation objects you can instantiate in your scripts, all the WMI moniker registration information is conveniently stored in the registry's HKEY_CLASSES_ROOT hive.

A moniker's syntax is implementation specific. That is, the developers of an automation technology that implements monikers determine the syntax, structure, and behavior of any moniker the technology recognizes and responds to. Consider Microsoft Active Directory Service Interfaces (ADSI) and WMI, for example. Both technologies make use of monikers as a way for you to describe objects in your scripts. However, each technology uses a unique style and syntax. ADSI uses a moniker string that makes sense to a directory service. WMI uses a string that accommodates a wide range of system-related information. From a systems administrator's perspective, a moniker is simply a string that's passed to VBScript's GetObject function. The string's contents determine what's returned to the calling script, which in turn governs the context in which the moniker can be used in the script.

In WMI, you can specify a moniker that returns a reference to the WMI Scripting Library's SWbemServices object, which you can use to invoke one of SWbemServices' methods (e.g., ExecQuery, Get, InstancesOf). You can specify a moniker that returns a reference to an SWbemObjectSet representing a collection of WMI objects to manage. And you can create a moniker that returns a reference to a discrete SWbemObject. The fact that the WMI moniker syntax can retrieve all these object types gives you an idea of the power and flexibility monikers provide.

WMI Moniker Basics
WMI monikers can consist of three parts: one mandatory and two optional components. The mandatory component is the "winmgmts:" prefix. All WMI monikers must begin with "winmgmts:", as the following statement shows:

Set wmiServices = _
  GetObject("winmgmts:")

The moniker in this case is the string "winmgmts:" that's passed to VBScript's GetObject function. Although I used all lowercase letters to enter the string in this example, you can use whatever case you like. "WinMgmts:", "WINMGMTS:", and "winmgmts:" all produce the same result.

A moniker that consists of only the "winmgmts:" prefix is the most basic form of a WMI moniker. The result is always a reference to the WMI Scripting Library's SWbemServices object, which represents a connection to the WMI service on the local computer. Under the covers, the "winmgmts:" moniker maps to HKEY_ CLASSES_ROOT\WINMGMTS, which maps to HKEY_CLASSES_ROOT\CLSID\ {172BDDF8-CEEA-11D1-8B05-00600806 D9B6}, which in turn points to C:\winnt\system32\wbem\wbemdisp.dll, which is the DLL containing the WMI Scripting Library.

After you've created this reference, you can invoke one of SWbemServices' methods to dive deeper into the WMI Scripting Object Model, as the statements in Listing 1 show. This example uses the "winmgmts:" moniker to initialize a variable named wmiServices. WmiServices subsequently invokes the InstancesOf method that the SWbemServices object provides. Although this example is perfectly acceptable, you don't really need two lines of script to retrieve all Win32_LogicalDisk instances. You can just as easily perform the task with the one line of script that Listing 2 shows.

Listing 2 leverages the fact that the "winmgmts:" moniker can immediately invoke SWbemServices' InstancesOf method to return an SWbemServices object. Both examples produce identical results in the form of an SWbemObjectSet collection containing all instances of the Win32_LogicalDisk class on the local computer. I can call just as easily the SWbemServices ExecQuery method or any other method that the SWbemServices object provides. In fact, if the objective of my script is to simply enumerate and echo all Win32_LogicalDisk instances, I can get by with just the statements in Listing 3. If you understand the most basic WMI moniker's relationship with the WMI Scripting Library, you can begin to construct concise and powerful WMI statements.

WMI Security-Settings Component
The second and a sometimes-optional part of WMI monikers is the security-settings component, which lets you specify several different security settings for the WMI connection. The security settings you can control as part of the moniker string are

• impersonation level, expressed as "winmgmts:{impersonationLevel=Value}"
• authentication level, expressed as "winmgmts:{authenticationLevel=Value}"
• authenticating authority, expressed as "winmgmts:{authority=ntlmdomain:DomainName}" or "winmgmts:{authority=kerberos:DomainName\ServerName}"
• privileges to grant or deny, expressed as "winmgmts:{(Security,!RemoteShutdown)}"

The first two settings, impersonationLevel and authenticationLevel, aren't specific to WMI but rather to Distributed COM (DCOM). WMI uses DCOM to access the WMI infrastructure on remote computers. In the context of WMI, impersonation governs the degree to which your script lets a remote WMI service carry out tasks for you. DCOM supports four levels of impersonation: Anonymous, Identify, Impersonate, and Delegate.

Anonymous impersonation hides your credentials, and the Identify value permits a remote object to query your credentials; neither level lets the remote object impersonate your security context. WMI scripts that use one of these two settings to access remote computers will generally fail. The Impersonate value lets the remote WMI service use your security context to perform the requested operation. A remote WMI request that uses the Impersonate setting typically succeeds if your credentials have sufficient privileges to perform the intended operation. The Delegate value lets the remote WMI service pass your credentials to other objects and is generally considered a security risk.

Some confusion surrounds the impersonationLevel setting because WMI's default impersonation behavior varies according to the WMI version on the target computer. WMI versions earlier than version 1.5 use Identify as the default impersonationLevel setting. This setting forces WMI scripts that connect to remote computers to include impersonationLevel=Impersonate as part of any moniker string. In WMI 1.5 in Windows 2000, Microsoft changed the default impersonationLevel setting to Impersonate. You can use the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WBEM\Scripting\Default Impersonation Level registry subkey to locate and manage this setting.

   Previous  [1]  2  Next