How to: Connect to WMI Objects

Article
08/18/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

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

You can connect to a WMI object in two ways:

Retrieve an instance of an object using the GetObject function with a moniker string in the input parameter.
Use this method for convenience, because 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 can be less efficient than the equivalent code that explicitly connects to WMI. If application performance is a consideration, consider creating an SWbemLocator object.
Create anSWbemLocator object and use the ConnectServer method to log on to a namespace.
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, whereas using a moniker only returns a generalized GetObject error if it fails.

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

Using a Moniker to Connect to an Object's Namespace

A moniker is a standard Component Object Model (COM) mechanism for encapsulating the location and binding of another COM object.

To connect to a WMI object with a moniker

Pass the name of the WMI Scripting Library's moniker (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\MSSV2:Deployment=@")
```

The moniker string format is very similar to a standard WMI object path. For more information, see WMI Object Path Requirements.

A moniker has the following parts:

Prefix "winmgmts:" (mandatory)
Security settings component (optional)
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 Microsoft 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 SWbemLocator.ConnectServer to Connect to an Object's Namespace

To connect to a WMI object with SWbemLocator

Call the SWbemLocator.ConnectServer method.

The ConnectServer method returns an SWbemServices object bound to the specified namespace. If an strNameSpace parameter is not provided, it defaults to the namespace configured as the default namespace for scripting.
Use the methods of the SWbemServices object to perform operations against a namespace on a local computer 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\MSSV2")
Set objDeployment = objServices.Get("Deployment=@")
```

Using Credentials and Privileges When Making the Connection

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

To set authentication and impersonation levels with a moniker string

Use code similar to the following to set authentication and impersonation levels with a moniker string.

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

To set authentication and impersonation levels with SWbemLocator

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.
```
Set objLocator = CreateObject("WbemScripting.SWbemLocator")
objLocator.Security_.AuthenticationLevel = wbemAuthenticationLevelPkt
Set objServices = objLocator.ConnectServer()
```

To enable or disable specific Windows XP privileges

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

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

To get more detailed error information

Use the error codes provided by the SWbemLocator.ConnectServer method to get more information about connection errors.

When SWbemLocator.ConnectServer is complete, the Err object can contain one of the error codes in the following table.

Error	Description
wbemErrAccessDenied0x80041003	The current or specified user name and password were not valid or authorized to make the connection.
wbemErrFailed0x80041001	Unspecified error.
wbemErrInvalidNamespace0x8004100E	The specified namespace did not exist on the server.
wbemErrInvalidParameter0x80041008	An invalid parameter was specified or the namespace could not be parsed.
wbemErrOutOfMemory0x80041006	Not enough memory to complete the operation.
wbemErrTransportFailure0x80041015	A networking error occurred, preventing normal operation.

Other Microsoft Distributed Component Object Model (DCOM) errors can also be reported, for example, DCOM "access denied" errors.

Connecting to a Singleton Class

A singleton is the sole instance of a class. The MSS class is a singleton class, so there is only a single instance of it on any particular computer.

To connect to a singleton class object

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 example.
```
Set objMSS = GetObject("winmgmts:\\" & strHostname &
"\root\MSSV2:MSS=@")
```

Connecting to Instance Classes

Instance classes can have multiple copies for each computer. The Application and TrustedSIPPeer classes are instance classes, so any computer running Speech Server can contain more than one instance of each.

To connect to an instance class object

Use key properties to distinguish between the various instances of an instance class when connecting to a specific instance object.

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 example code demonstrates the GetObject function with a moniker string referring to an instance of the Application class.
```
Set objMSS = GetObject("winmgmts:\\" & strHostname &
"\root\MSSV2:Application='WelcomeToMSS'")
```

The following table lists the key properties for the instance classes.

Class	Key Property
Application	Name
Deployment	Name
Service	DeploymentName
SIPPeer	Name
TrustedSIPPeer	Name