Connecting to WMI Objects

Article
08/28/2007

Connecting to WMI Objects

This topic contains information about object namespaces and authentication, and describes techniques for connecting to Windows Management Instrumentation (WMI) objects.

Connecting to a Specified WMI Namespace

WMI objects are contained in namespaces, so the first step in connecting to an object is to connect to that object's namespace. For information on what namespaces are and how they are useful, see the MSDN article Understanding XML Namespaces. For information on WMI object paths, see the MSDN Library article Describing the Location of a WMI Object.

Choose to connect to a WMI object in one of two ways:

Retrieve an instance of an object using the GetObject function with a moniker string in the input parameter.
Create an SWbemLocator object, and then use the ConnectServer method to log on to a namespace.

Consider the relative advantages of each of the two choices when deciding which one to use.

Method	Advantages
Moniker string	Use this method for convenience, as it requires only a single statement to make the connection. The moniker always uses the credentials of the currently logged on user. Although monikers provide more direct access to objects, in certain circumstances, repeated use of monikers may be less efficient than the equivalent code that explicitly connects to WMI. If application performance is a consideration, instead consider creating an SWbemLocator object.
SWbemLocator.ConnectServer Method	Use this method to specify locale, authentication scheme, or security flags, as well as user and password on remote computers. The ConnectServer method also provides a variety of specific error codes if a connection fails, while using a moniker only returns a generalized GetObject error if it fails.

Moniker string

Use this method for convenience, as it requires only a single statement to make the connection. The moniker always uses the credentials of the currently logged on user. Although monikers provide more direct access to objects, in certain circumstances, repeated use of monikers may be less efficient than the equivalent code that explicitly connects to WMI. If application performance is a consideration, instead consider creating an SWbemLocator object.

SWbemLocator.ConnectServer Method

Use this method to specify locale, authentication scheme, or security flags, as well as user and password on remote computers. The ConnectServer method also provides a variety of specific error codes if a connection fails, while using a moniker only returns a generalized GetObject error if it fails.

Using Monikers

A moniker is a standard COM mechanism for encapsulating the location and binding of another COM object. To connect to a WMI object using a moniker, pass the name of the WMI Scripting Library's moniker, which is "winmgmts:" followed by the name of the target computer as the parameter to the VBScript GetObject function. For example, the following statement connects to the Deployment object.

Set objDeployment = GetObject("winmgmts:root\MSS:Deployment=@")

The moniker string format is very similar to a standard WMI object path. For more information, see the MSDN Library article WMI Object Path Requirements. A moniker has the following parts:

The prefix "winmgmts:" (mandatory)
A security settings component (optional)
A WMI object path component (optional)

The following default assignments are allowed when specifying the object path:

The local computer name in the object path can be replaced with '.' . The computer name can also be omitted from the object path, in which case the local computer is assumed. The following statements are all equivalent.
```
'computer name is omitted, local computer is assumed
```

GetObject("winmgmts:root\cimv2:Win32_LogicalDisk='C:'")

'local computer name is specified using '.' GetObject("winmgmts:\.\root\cimv2:Win32_LogicalDisk='C:'")

'localhost is specified GetObject("winmgmts:\localhost\root\cimv2:Win32_LogicalDisk='C:'")

'computer name 'mycomputer' is specified GetObject("winmgmts:\mycomputer\root\cimv2: Win32_LogicalDisk='C:'")

The namespace can be omitted from the object path, in which case the default namespace is assumed. This is determined by the value of the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\WBEM\Scripting\Default Namespace, the default value of which is root\cimv2 for Windows XP.
A class or instance can also be specified, in which case the returned object is a WMI object rather than a services object.

Note If a class or instance is specified, it is not possible to omit the namespace when specifying the computer name.

The following VBScript example demonstrates how to combine security and locale parameters in a moniker.

Set myobj = GetObject("WINMGMTS:" _
            & "{impersonationLevel=impersonate," _
            & "authenticationLevel=pktPrivacy," _
            & "authority=ntlmdomain:mydomain," _
            & "(Debug,!RemoteShutdown)}" _
            & "[locale=ms_409]" _
            & "!\\User1\ROOT\CIMV2:Win32_LogicalDisk=""C:""")

wscript.echo "File system = " & myobj.filesystem

Using the SWbemLocator.ConnectServer Method

The ConnectServer method returns an SWbemServices object bound to the specified namespace. If no strNameSpace parameter is provided, it defaults to the namespace configured as the default namespace for scripting. Use the methods of an SWbemServices object to perform operations against a namespace on a local or remote host. For example, the following statements connect to a specified computer, and get an instance of the Deployment object.

Set objLocator = CreateObject("WbemScripting.SWbemLocator")
Set objServices = objLocator.ConnectServer(strHostname, "root\MSS")
Set objDeployment = objServices.Get("Deployment=@")

Using Credentials and Privileges When Making the Connection

For best results, set application process security using the default authentication and impersonation levels that the WMI provides. The Component Object Model (COM) uses the authentication and impersonation levels to determine how much security a process must have to access a client application process.

Using Moniker Strings

The following example demonstrates how to set the authentication and impersonation levels using a moniker string.

Set Service = GetObject("winmgmts:{impersonationLevel=impersonate,authenticationLevel=pktPrivacy}!root\cimv2")

Using the SWbemLocator Object

Use the AuthenticationLevel and ImpersonationLevel properties of the SWbemSecurity object to set the COM Authentication and Impersonation levels for a WMI object, as shown in the following code sample.

Set objLocator = CreateObject("WbemScripting.SWbemLocator")
objLocator.Security_.AuthenticationLevel = wbemAuthenticationLevelPkt
Set objServices = objLocator.ConnectServer()

Use the Privileges property of the SWbemSecurity object to enable or disable specific Windows XP privileges, as shown in the following statements.

' Connect to local WMI with security privileges enabled
Set objLocator = CreateObject("WbemScripting.SWbemLocator")
objLocator.Security_.Privileges.AddAsString "SeSecurityPrivilege"
Set objServices = objLocator.ConnectServer()

Diagnosing WMI Connection Errors

In some cases, the connection errors returned by the GetObject method when connecting with moniker strings might not provide enough detail. Use the error codes provided by the SWbemLocator.ConnectServer method to get more detail on connection errors. When SWbemLocator.ConnectServer completes, the Err object may contain one of the error codes in the following table. Other Microsoft Distributed Component Object Model (DCOM) errors may also be reported, for example DCOM "access denied" errors.

Error	Meaning
wbemErrAccessDenied 0x80041003	The current or specified user name and password were not valid or authorized to make the connection.
wbemErrFailed 0x80041001	Unspecified error.
wbemErrInvalidNamespace 0x8004100E	The specified namespace did not exist on the server.
wbemErrInvalidParameter 0x80041008	An invalid parameter was specified, or the namespace could not be parsed.
wbemErrOutOfMemory 0x80041006	Not enough memory to complete the operation.
wbemErrTransportFailure 0x80041015	A networking error occurred, preventing normal operation.

Connecting to Singleton Classes

A singleton is the sole instance of a class. The TAS, and SES classes are singleton classes, so there is only a single instance of each on any particular computer. Use an object path to describe the location of an instance of a class within a namespace. For singleton classes, the object path consists of the class name followed by the "=@" notation, as in the following statement.

Set objTelServer = GetObject("winmgmts:\\" & strHostname & "\root\MSS:TAS=@")

Connecting to Instance Classes

Instance classes can have multiple copies per computer. The EngineConfiguration and TrustedSite classes are instance classes, so any one Speech Server may contain more than one instance of each. Use key properties to distinguish between the various instances of an instance class. For instance classes with only one key property, the object path consists of the class name followed by the value of the key property. The following sample statement demonstrates the GetObject function with a moniker string referring to an instance of the EngineConfiguration class.

Set objTelServer = GetObject("winmgmts:\\" & strHostname & "\root\MSS:EngineConfiguration='DefaultVoice'")

The following table lists the key properties for each of the Speech Server instance classes.

Class	Key Property
EngineConfiguration	ConfigName
TrustedSites	Hostname

Connecting to WMI Objects