Método SWbemServices.ExecQuery

O método ExecQuery do objeto SWbemServices executa uma consulta para recuperar objetos. Esses objetos estão disponíveis por meio da coleção SWbemObjectSet retornada.

Esse método é chamado no modo semissíncrono. Para obter mais informações, consulte Chamar um método.

Para conferir uma explicação dessa sintaxe, confira Convenções de documentação para API de script.

Sintaxe

objWbemObjectSet = .ExecQuery( _
  ByVal strQuery, _
  [ ByVal strQueryLanguage ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ] _
)

Parâmetros

strQuery

Obrigatórios. Cadeia de caracteres que contém o texto da consulta. Este parâmetro não pode ficar em branco. Para obter mais informações sobre como criar cadeias de caracteres de consulta do WMI, veja Como consultar com WQL e a referência da WQL.

strQueryLanguage [opcional]

Cadeia de caracteres que contém a linguagem de consulta a ser usada. Se especificado, esse valor deverá ser "WQL".

iFlags [opcional]

Inteiro que determina o comportamento da consulta e determina se essa chamada retorna imediatamente. O valor padrão para esse parâmetro é wbemFlagReturnImmediately. Esse parâmetro pode aceitar os valores a seguir.

wbemFlagForwardOnly (32 (0x20))

Faz com que um enumerador somente de encaminhamento seja retornado. Normalmente, os enumeradores apenas de encaminhamento são mais rápidos e usam menos memória do que os enumeradores convencionais, mas eles não permitem chamadas para SWbemObject.Clone_.

wbemFlagBidirectional (0 (0x0))

Faz com que a WMI retenha ponteiros para objetos da enumeração até que o cliente libere o enumerador.

wbemFlagReturnImmediately (16 (0x10))

Faz com que a chamada retorne imediatamente.

wbemFlagReturnWhenComplete (0 (0x0))

Faz com que essa chamada seja bloqueada até a conclusão da consulta. Esse sinalizador chama o método no modo síncrono.

wbemQueryFlagPrototype (2 (0x2))

Usado para criação de protótipos. Esse sinalizador impede a execução da consulta e retorna um objeto que se assemelha a um objeto de resultado típico.

wbemFlagUseAmendedQualifiers (131072 (0x20000))

Faz com que o WMI retorne dados de aditamento da classe com a definição da classe base. Para obter mais informações, consulte Localizar informações de classe WMI.

objWbemNamedValueSet [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 não ocorrer nenhum erro, esse método retornará um objeto SWbemObjectSet. Esta é uma coleção de objetos que contém o conjunto de resultados da consulta. O chamador pode examinar a coleção usando a implementação de coleções para a linguagem de programação que você está usando. Para obter mais informações, consulte Acessar uma coleção.

Códigos do Erro

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

wbemErrAccessDenied - 2147749891 (0x80041003)

O usuário atual não tem permissão para exibir o conjunto de resultados.

wbemErrFailed – 2147749889 (0x80041001)

Erro não especificado.

wbemErrInvalidParameter – 2147749896 (0x80041008)

Foi especificado um parâmetro inválido.

wbemErrInvalidQuery - 2147749911 (0x80041017)

A sintaxe da consulta não é válida.

wbemErrInvalidQueryType - 2147749912 (0x80041018)

Não há suporte para a linguagem de consulta solicitada.

wbemErrOutOfMemory – 2147749894 (0x80041006)

Não há memória suficiente para concluir a operação.

Comentários

A ExecQuery é uma das chamadas mais usadas para recuperar informações do WMI. Uma chamada padrão para ExecQuery é semelhante à seguinte:

strComputer = "."
Set objWMIService = GetObject("winmgmts:" & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

Set colServices = objWMIService.ExecQuery ("Select * from Win32_Service where Name='Alerter'")
For Each objService in colServices
    Return = objService.StopService()
    If Return <> 0 Then
        Wscript.Echo "Failed " &VBNewLine & "Error code = " & Return 
    Else
       WScript.Echo "Succeeded"
    End If
Next

Observe que você cria o objeto SWbemServices com um moniker que representa o namespace e a segurança apropriados e, em seguida, faz a chamada ExecQuery por meio do serviço. Para obter uma discussão mais completa, consulte Criando um script do WMI e Enumerar WMI.

Assim como o método InstancesOf, o método ExecQuery sempre retorna uma coleção SWbemObjectSet. Portanto, o script do WMI deve enumerar a coleção que ExecQuery retorna para acessar cada instância de recurso gerenciado na coleção, conforme mostrado aqui:

strComputer = "."
Set objSWbemServices = GetObject("winmgmts:\\" & strComputer & "\root\cimv2")
Set colSWbemObjectSet = objSWbemServices.ExecQuery _
   ("SELECT * FROM Win32_Service")
For Each objSWbemObject In colSWbemObjectSet
    Wscript.Echo "Name: " & objSWbemObject.Name
Next

Outros métodos SWbemServices que retornam um SWbemObjectSet incluem AssociatorsOf, ReferencesTo e SubclassesOf.

Não é um erro para a consulta retornar um conjunto de resultados vazio. Esse método ExecQuery retorna as propriedades de chave independentemente de a propriedade de chave ser solicitada ou não no argumento strQuery. Se ocorrer um erro ao executar esse método e você não usar o sinalizador wbemFlagReturnImmediately , o objeto de Erro não será definido até que você tente acessar o conjunto de objetos retornado. No entanto, caso use o sinalizador wbemFlagReturnWhenComplete, o objeto de Erro será definido quando o método ExecQuery for chamado.

Existem limites no número de palavras-chave AND e OR que podem ser usadas nas consultas WQL. Um grande número de palavras-chave da WQL que são usadas em uma consulta complexa pode fazer com que o WMI retorne o código de erro WBEM_E_QUOTA_VIOLATION como um valor HRESULT. O limite de palavras-chave WQL depende da complexidade da consulta.

Exemplos

O exemplo de código VBScript a seguir localiza todas as unidades de disco no computador local e exibe a ID do dispositivo e o tipo da unidade de disco.

Set colDisks = GetObject( _
    "Winmgmts:").ExecQuery("Select * from Win32_LogicalDisk")
For Each objDisk in colDisks
 
    Select Case objDisk.DriveType
        Case 1
            Wscript.Echo "No root directory. Drive type could not be determined."
        Case 2
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Removable drive" 
        Case 3
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Local hard disk" 
        Case 4
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Network disk" 
        Case 5
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = Compact disk" 
        Case 6
            Wscript.Echo "DeviceID= "& objDisk.DeviceID & "  DriveType = RAM disk" 
        Case Else
            Wscript.Echo "Drive type could not be determined."
    End Select
Next

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_SWbemServices
IID	IID_ISWbemServices

Confira também

SWbemServices

SWbemServices.Get

Como consultar com WQL

Como criar um script do WMI

Enumeração do WMI