Método SWbemLocator.ConnectServer

Artigo
07/03/2023

O método ConnectServer do objeto SWbemLocator se conecta ao namespace no computador especificado no parâmetro strServer. O computador de destino pode ser local ou remoto, mas precisa ter o WMI instalado. Para obter exemplos e uma comparação com o tipo de conexão moniker, confira Criar um script do WMI.

Começando no Windows Vista, SWbemLocator.ConnectServer pode se conectar a computadores que executam IPv6 usando um endereço IPv6 no parâmetro strServer. Para obter mais informações, consulte Suporte a IPv6 e IPv4 na WMI.

Para obter uma explicação dessa sintaxe, confira Convenções de documentação para a API de Script.

Sintaxe

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

Parâmetros

strServer [in, opcional]

Nome do computador ao qual você está se conectando. Se o computador remoto estiver em um domínio diferente da conta de usuário com a qual você fizer logon, use o nome do computador totalmente qualificado. Se você não fornecer esse parâmetro, a chamada usará o computador local como padrão.

Exemplo: server1.network.fabrikam

Você também pode usar um endereço IP nesse parâmetro. Se o endereço IP estiver no formato IPv6, o computador de destino deverá estar executando IPv6. Um endereço em IPv4 se parece com 123.123.123.123

Um endereço IP no formato IPv6 se parece com 2010:836B:4179::836B:4179

Para obter mais informações sobre DNS e IPv4, confira a seção Comentários.

strNamespace [in, opcional]

Cadeia de caracteres que especifica o namespace no qual você faz logon. Por exemplo, para fazer logon no namespace root\default, use root\default. Se você não especificar esse parâmetro, ele usará como padrão o namespace configurado como namespace padrão para scripts. Para obter mais informações, consulte Criar um aplicativo ou script da WMI.

Exemplo: "root\CIMV2"

strUser [in, opcional]

Nome de usuário a ser usado para se conectar. A cadeia de caracteres pode estar no formato de um nome de usuário ou domínio\nome de usuário. Deixe esse parâmetro em branco para usar o contexto de segurança atual. O parâmetro strUser só deve ser usado com conexões com servidores do WMI remotos. Se você tentar especificar strUser para uma conexão do WMI local, a tentativa de conexão falhará. Se a autenticação Kerberos estiver em uso, o nome de usuário e a senha especificados em strUser e strPassword não poderão ser interceptados em uma rede. Você pode usar o formato UPN para especificar o strUser.

Exemplo: "NomeDeDominio\NomeDeUsuario"

Observação

Se um domínio for especificado em strAuthority, ele não deverá ser especificado aqui. Especificar o domínio nos dois parâmetros resulta em um erro de parâmetro inválido.

strPassword [in, opcional]

Cadeia de caracteres que especifica a senha a ser usada ao tentar se conectar. Deixe o parâmetro em branco para usar o contexto de segurança atual. O parâmetro strPassword só deve ser usado com conexões com servidores do WMI remotos. Se você tentar especificar strPassword para uma conexão do WMI local, a tentativa de conexão falhará. Se a autenticação Kerberos estiver em uso, o nome de usuário e a senha especificados em strUser e strPassword não poderão ser interceptados na rede.

strLocale [in, opcional]

Cadeia de caracteres que especifica o código de localização. Se quiser usar a localidade atual, deixe-a em branco. Se não estiver em branco, esse parâmetro deverá ser uma cadeia de caracteres que indica a localidade desejada em que as informações devem ser recuperadas. Para IDs de localidade da Microsoft, o formato da cadeia de caracteres é "MS_xxxx", em que xxxx é uma cadeia de caracteres no formato hexadecimal que indica o LCID. Por exemplo, o inglês americano apareceria como "MS_409".

strAuthority [in, opcional]

""

Esse parâmetro é opcional. No entanto, se for especificado, somente o Kerberos ou NTLMDomain poderão ser usados.

Kerberos:

Se o parâmetro strAuthority começar com a cadeia de caracteres "Kerberos:", a autenticação Kerberos será usada e esse parâmetro deverá conter um nome de entidade de segurança Kerberos. O nome da entidade de segurança Kerberos é especificado como Kerberos:domínio, como Kerberos:fabrikam, em que fabrikam é o servidor ao qual você está tentando se conectar.

Exemplo: "Kerberos:DOMÍNIO"

NTLMDomain:

Para usar a autenticação NTLM (NT Lan Manager), especifique-a como NTLMDomain:domínio, como NTLMDomain:fabrikam, em que fabrikam é o nome do domínio.

Exemplo: "NTLMDomain:DOMÍNIO"

Se você deixar esse parâmetro em branco, o sistema operacional negociará com o COM para determinar se a autenticação NTLM ou Kerberos deve ser usada. Esse parâmetro só deve ser usado com conexões com servidores do WMI remotos. Se você tentar definir a autoridade para uma conexão do WMI local, a tentativa de conexão falhará.

Observação

Se o domínio for especificado em strUser, que é o local preferencial, ele não poderá ser especificado aqui. Especificar o domínio nos dois parâmetros resulta em um erro de parâmetro inválido.

iSecurityFlags [in, opcional]

Usado para passar valores de sinalizador para ConnectServer.

0 (0x0)

Um valor de 0 para esse parâmetro faz com que a chamada para ConnectServer retorne somente após a conexão com o servidor ser estabelecida. Isso poderá fazer com que o programa pare de responder indefinidamente se a conexão não puder ser estabelecida.

wbemConnectFlagUseMaxWait (128 (0x80))

A chamada ConnectServer tem a garantia de retornar em 2 minutos ou menos. Use esse sinalizador para impedir que o programa pare de responder indefinidamente se a conexão não puder ser estabelecida.

objwbemNamedValueSet [in, opcional]

Normalmente, isso é indefinido. Caso contrário, esse será um objeto SWbemNamedValueSet cujos elementos representam as informações de contexto que podem ser usadas pelo provedor que está atendendo à solicitação. Um provedor que dê suporte ou exija essas informações deve documentar os nomes de valor reconhecidos, o tipo de dados do valor, os valores permitidos e a semântica.

Retornar valor

Se tiver êxito, o WMI retornará um objeto SWbemServices associado ao namespace especificado em strNamespace no computador especificado em strServer.

Códigos do Erro

Após a conclusão do método ConnectServer, o objeto Err poderá conter um dos códigos de erro da lista a seguir.

wbemErrAccessDenied – 2147749891 (0x80041003): O nome de usuário e a senha atuais ou especificados não eram válidos nem autorizados a fazer a conexão.
wbemErrFailed – 2147749889 (0x80041001): Erro não especificado.
wbemErrInvalidNamespace – 2147749902 (0x8004100E): O namespace especificado não existia no servidor.
wbemErrInvalidParameter – 2147749896 (0x80041008): Um parâmetro inválido foi especificado ou o namespace não pôde ser analisado.
wbemErrOutOfMemory – 2147749894 (0x80041006): Não há memória suficiente para concluir a operação.
wbemErrTransportFailure – 2147749909: Ocorreu um erro de rede, impedindo a operação normal.

Comentários

O método ConnectServer geralmente é usado ao se conectar a uma conta com um nome de usuário e credenciais de senha diferentes em um computador remoto, porque você não pode especificar uma senha diferente em uma cadeia de caracteres moniker. Para obter mais informações, consulte Conexão ao WMI em um computador remoto.

Usar um endereço IPv4 para se conectar a um servidor remoto pode gerar um comportamento inesperado. A causa provável são entradas DNS obsoletas no ambiente. Nessas circunstâncias, a entrada PTR obsoleta para o computador será usada, com resultados imprevisíveis. Para evitar esse comportamento, você pode acrescentar um ponto (".") ao endereço IP antes de chamar ConnectServer. Isso faz com que a pesquisa de DNS inversa falhe, mas pode permitir que a chamada ConnectServer tenha êxito no computador correto.

Exemplos

O exemplo de código VBScript a seguir descreve como se conectar a um computador remoto para obter dados de Win32_IP4RouteTable. O nome de domínio especificado em strDomain é usado em 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

O snippet do PowerShell a seguir acessa um servidor remoto e lista as classes de WMI disponíveis.

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Cabeçalho	Wbemdisp.h
Biblioteca de tipos	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemLocator
IID	IID_ISWbemLocator

Confira também

SWbemLocator
SWbemServices
Conectar-se ao WMI em um computador remoto
Criar um script do WMI

Compartilhar via

Método SWbemLocator.ConnectServer

Sintaxe

Parâmetros

Retornar valor

Códigos do Erro

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais