SWbemLocator.ConnectServer method

Artikel
01/07/2021

The ConnectServer method of the SWbemLocator object connects to the namespace on the computer that is specified in the strServer parameter. The target computer can be either local or remote, but it must have WMI installed. For examples and a comparison with the moniker type of connection, see Creating a WMI Script.

Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address in the strServer parameter. For more information, see IPv6 and IPv4 Support in WMI.

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

objwbemServices = .ConnectServer( _
  [ ByVal strServer ], _
  [ ByVal strNamespace ], _
  [ ByVal strUser ], _
  [ ByVal strPassword ], _
  [ ByVal strLocale ], _
  [ ByVal strAuthority ], _
  [ ByVal iSecurityFlags ], _
  [ ByVal objwbemNamedValueSet ] _
)

Parameters

strServer [in, optional]

Computer name to which you are connecting. If the remote computer is in a different domain than the user account under which you log in, then use the fully qualified computer name. If you do not provide this parameter, the call defaults to the local computer.

Example: server1.network.fabrikam

You also can use an IP address in this parameter. If the IP address is in IPv6 format, the target computer must be running IPv6. An address in IPv4 looks like 123.123.123.123

An IP address in IPv6 format looks like 2010:836B:4179::836B:4179

For more information on DNS and IPv4, see the Remarks section.

strNamespace [in, optional]

String that specifies the namespace to which you log on. For example, to log on to the root\default namespace, use root\default. If you do not specify this parameter, it defaults to the namespace that is configured as the default namespace for scripting. For more information, see Creating a WMI Application or Script.

Example: "root\CIMV2"

strUser [in, optional]

User name to use to connect. The string can be in the form of either a user name or a Domain\Username. Leave this parameter blank to use the current security context. The strUser parameter should only be used with connections to remote WMI servers. If you attempt to specify strUser for a local WMI connection, the connection attempt fails. If Kerberos authentication is in use, then the username and password that is specified in strUser and strPassword cannot be intercepted on a network. You can use the UPN format to specify the strUser.

Example: "DomainName\UserName"

Note

If a domain is specified in strAuthority, then the domain must not be specified here. Specifying the domain in both parameters results in an Invalid Parameter error.

strPassword [in, optional]

String that specifies the password to use when attempting to connect. Leave the parameter blank to use the current security context. The strPassword parameter should only be used with connections to remote WMI servers. If you attempt to specify strPassword for a local WMI connection, the connection attempt fails. If Kerberos authentication is in use then the username and password that is specified in strUser and strPassword cannot be intercepted on the network.

strLocale [in, optional]

String that specifies the localization code. If you want to use the current locale, leave it blank. If not blank, this parameter must be a string that indicates the desired locale where information must be retrieved. For Microsoft locale identifiers, the format of the string is "MS_xxxx", where xxxx is a string in the hexadecimal form that indicates the LCID. For example, American English would appear as "MS_409".

strAuthority [in, optional]

""

This parameter is optional. However, if it is specified, only Kerberos or NTLMDomain can be used.

Kerberos:

If the strAuthority parameter begins with the string "Kerberos:", then Kerberos authentication is used and this parameter should contain a Kerberos principal name. The Kerberos principal name is specified as Kerberos:domain, such as Kerberos:fabrikam where fabrikam is the server to which you are attempting to connect.

Example: "Kerberos:DOMAIN"

NTLMDomain:

To use NT Lan Manager (NTLM) authentication, you must specify it as NTLMDomain:domain, such as NTLMDomain:fabrikam where fabrikam is the name of the domain.

Example: "NTLMDomain:DOMAIN"

If you leave this parameter blank, the operating system negotiates with COM to determine whether NTLM or Kerberos authentication is used. This parameter should only be used with connections to remote WMI servers. If you attempt to set the authority for a local WMI connection, the connection attempt fails.

Note

If the domain is specified in strUser, which is the preferred location, then it must not be specified here. Specifying the domain in both parameters results in an Invalid Parameter error.

iSecurityFlags [in, optional]

Used to pass flag values to ConnectServer.

0 (0x0)

A value of 0 for this parameter causes the call to ConnectServer to return only after the connection to the server is established. This could cause your program to stop responding indefinitely if the connection cannot be established.

wbemConnectFlagUseMaxWait (128 (0x80))

The ConnectServer call is guaranteed to return in 2 minutes or less. Use this flag to prevent your program from ceasing to respond indefinitely if the connection cannot be established.

objwbemNamedValueSet [in, optional]

Typically, this is undefined. Otherwise, this is an SWbemNamedValueSet object whose elements represent the context information that can be used by the provider that is servicing the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

Return value

If successful, WMI returns an SWbemServices object that is bound to the namespace that is specified in strNamespace on the computer that is specified in strServer.

Error codes

After the completion of the ConnectServer method, the Err object may contain one of the error codes in the following list.

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

Remarks

The ConnectServer method is often used when connecting to an account with a different username and password credentials on a remote computer because you cannot specify a different password in a moniker string. For more information, see Connecting to WMI on a Remote Computer.

Using an IPv4 address to connect to a remote server may result in unexpected behavior. The likely cause is stale DNS entries in your environment. In these circumstances, the stale PTR entry for the machine will be used, with unpredictable results. To avoid this behavior, you can append a period (".") to the IP address before calling ConnectServer. This causes the reverse DNS lookup to fail, but may allow the ConnectServer call to succeed on the correct machine.

Examples

The following VBScript code example describes how to connect to a remote computer to obtain Win32_IP4RouteTable data. The domain name that is specified in strDomain is used in strAuthority.

Const intMin = 3600
strComputer = "RemoteComputer" 
strDomain = "DomainName"  
Wscript.StdOut.Write "Please enter your user name:"
strUser = Wscript.StdIn.ReadLine 
Set objPassword = CreateObject("ScriptPW.Password")
Wscript.StdOut.Write "Please enter your password:"
strPassword = objPassword.GetPassword()
Wscript.Echo

Set objSWbemLocator = CreateObject("WbemScripting.SWbemLocator") 
Set objWMIService = objSWbemLocator.ConnectServer(strComputer, _ 
                                                  "root\CIMV2", _ 
                                                  strUser, _ 
                                                  strPassword, _ 
                                                  "MS_409", _ 
                                                  "NTLMDomain:" + strDomain) 
Set colItems = objWMIService.ExecQuery("SELECT * FROM Win32_IP4RouteTable",,48) 
For Each objItem in colItems
    WScript.Echo "Age in Minutes: " & int(objItem.Age/intMin) & VBNewLine _
               & "Description:    " & objItem.Description & VBNewLine _
               & "Destination:    " & objItem.Destination & VBNewLine _
               & "InterfaceIndex: " & objItem.InterfaceIndex & VBNewLine _
               & "Mask:           " & objItem.Mask & VBNewLine _
               & "Metric1:        " & objItem.Metric1 & VBNewLine _
               & "Metric2:        " & objItem.Metric2 & VBNewLine _
               & "Metric3:        " & objItem.Metric3 & VBNewLine _
               & "Metric4:        " & objItem.Metric4 & VBNewLine _
               & "Metric5:        " & objItem.Metric5 & VBNewLine _
               & "Name:           " & objItem.Name & VBNewLine _
               & "NextHop:        " & objItem.NextHop & VBNewLine _
               & "Protocol:       " & objItem.Protocol & VBNewLine _
               & "Type: " & objItem.Type
    WScript.Echo
   </example>
Next

The following PowerShell snippet access a remote server and lists the available WMI classes.

$NameSpace = 'root\ccm'
$ComputerName = 'sccm.company.com'
$WbemLocator = New-Object -ComObject "WbemScripting.SWbemLocator"
$WbemServices = $WbemLocator.ConnectServer($ComputerName, $Namespace)
$WbemClasses = $WbemServices.SubclassesOf()
$WbemClasses

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Wbemdisp.h
Type library	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemLocator
IID	IID_ISWbemLocator

Delen via