Método SWbemLocator.ConnectServer

  • Artigo
  • 7 minutos para ler

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

A partir do Windows Vista, o SWbemLocator.ConnectServer pode se conectar com computadores que executam o IPv6 usando um endereço IPv6 no parâmetro strServer. Para obter mais informações, consulte o suporte IPv6 e IPv4 no WMI.

Para obter uma explicação dessa sintaxe, consulte As Convenções de Documento para a API de Scripts.

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 na qual você faz logon, use o nome do computador totalmente qualificado. Se você não fornecer esse parâmetro, a chamada será padrão para o computador local.

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 o IPv6. Um endereço no 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, consulte 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 raiz\padrão, use raiz\padrão. Se você não especificar esse parâmetro, ele será o padrão para o namespace configurado como o namespace padrão para scripts. Para obter mais informações, consulte Criando um aplicativo ou script WMI.

Exemplo: "root\CIMV2"

strUser [in, opcional]

Nome de usuário a ser usado para se conectar. A cadeia de caracteres pode estar na forma de um nome de usuário ou um 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 WMI remotos. Se você tentar especificar o strUser para uma conexão 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 no strUser e strPassword não poderão ser interceptados em uma rede. Você pode usar o formato UPN para especificar o strUser.

Exemplo: "DomainName\UserName"

Observação

Se um domínio for especificado em strAuthority, o domínio não deverá ser especificado aqui. Especificar o domínio em ambos os 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 WMI remotos. Se você tentar especificar strPassword para uma conexão 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 no 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 você quiser usar a localidade atual, deixe-a em branco. Se não estiver em branco, esse parâmetro deve ser uma cadeia de caracteres que indica a localidade desejada em que as informações devem ser recuperadas. Para identificadores de localidade da Microsoft, o formato da cadeia de caracteres é "MS_xxxx", em que xxxx é uma cadeia de caracteres no formulário 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 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:domain, como Kerberos:fabrikam onde fabrikam está o servidor ao qual você está tentando se conectar.

Exemplo: "Kerberos:DOMAIN"

NTLMDomain:

Para usar a autenticação NTLM (NTLM), especifique-a como NTLMDomain:domain, como NTLMDomain:fabrikam onde fabrikam está o nome do domínio.

Exemplo: "NTLMDomain:DOMAIN"

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

Observação

Se o domínio for especificado no strUser, que é o local preferencial, ele não deverá ser especificado aqui. Especificar o domínio em ambos os 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 0 para esse parâmetro faz com que a chamada para ConnectServer retorne somente depois que a conexão com o servidor for estabelecida. Isso pode 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 seu programa cesse de responder indefinidamente se a conexão não puder ser estabelecida.

objwbemNamedValueSet [in, opcional]

Normalmente, isso é indefinido. Caso contrário, esse é 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 que está associado ao namespace especificado no strNamespace no computador especificado no strServer.

Códigos do Erro

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

wbemErrAccessDenied - 2147749891 (0x80041003)

O nome de usuário e a senha atuais ou especificados não eram válidos ou 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)

Memória insuficiente 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 de moniker . Para obter mais informações, consulte Conectar-se ao WMI em um computador remoto.

Usar um endereço IPv4 para se conectar a um servidor remoto pode resultar em um comportamento inesperado. A causa provável são entradas DNS obsoletas em seu ambiente. Nessas circunstâncias, a entrada de PTR obsoleta para o computador será usada, com resultados imprevisíveis. Para evitar esse comportamento, você pode acrescentar um período (".") ao endereço IP antes de chamar o ConnectServer. Isso faz com que a pesquisa DNS reversa falhe, mas pode permitir que a chamada do 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 Win32_IP4RouteTable . O nome de domínio especificado no 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 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

Conectando-se ao WMI em um computador remoto

Criando um script WMI