Pesquisando com ActiveX Data Objects (ADO)

O modelo ActiveX Data Object (ADO) consiste em objetos listados na tabela a seguir.

Objeto	Descrição
Conexão	Uma conexão aberta com uma fonte de dados OLE DB, como ADSI.
Comando	Define um comando específico a ser executado na fonte de dados.
Parâmetro	Uma coleção opcional para quaisquer parâmetros a serem fornecidos ao objeto de comando.
Conjunto de Registros	Um conjunto de registros de uma tabela, objeto de comando ou sintaxe SQL. Um conjunto de registros pode ser criado sem qualquer objeto de conexão subjacente.
Campo	Uma única coluna de dados em um conjunto de registros.
Propriedade	Uma coleção de valores fornecidos pelo provedor para o ADO.
Erro	Contém dados sobre erros de acesso a dados. Atualizado quando ocorre um erro em uma única operação.

Para que o ADO se comunique com o ADSI, deve haver, pelo menos, dois objetos ADO: Connection e RecordSet. Esses objetos ADO servem para autenticar usuários e enumerar resultados, respectivamente. Normalmente, você também usará um objeto Command para manter uma conexão ativa, especificar parâmetros de consulta, como tamanho da página e escopo de pesquisa, e executar uma consulta. Para obter mais informações sobre a sintaxe do filtro de pesquisa, consulte Sintaxe do filtro de pesquisa.

O objeto Connection carrega o provedor OLE DB e valida as credenciais do usuário. No Visual Basic, chame a função CreateObject com "ADODB. Connection" para criar uma instância de um objeto Connection e, em seguida, defina a propriedade Provider do objeto Connection como "ADsDSOObject". "ADODB. Connection" é o ProgID do objeto Connection e "ADsDSOObject" é o nome do provedor OLE DB no ADSI. Se nenhuma credencial for especificada, as credenciais do usuário conectado no momento serão usadas.

O exemplo de código a seguir mostra como criar uma instância de um objeto Connection .

Set con = CreateObject("ADODB.Connection")
con.Provider = "ADsDSOObject"

O exemplo de código a seguir mostra como criar uma instância de um objeto Connection .

<%
Set con = Server.CreateObject("ADODB.Connection")
con.Provider = "ADsDSOObject"
%>

O exemplo de código a seguir mostra como criar uma instância de um objeto Connection . Lembre-se de que você deve incluir a biblioteca de tipos ADO (msadoXX.dll) como uma das referências no projeto Visual Basic.

Dim Con As New Connection
con.Provider = "ADsDSOObject"

Especifique os dados de autenticação do usuário definindo as propriedades do objeto Connection . A tabela a seguir lista as propriedades de autenticação de usuário suportadas pelo ADSI.

Propriedade	Descrição
"ID do usuário"	Uma cadeia de caracteres que identifica o usuário cujo contexto de segurança é usado ao executar a pesquisa. Para obter mais informações sobre o formato da cadeia de caracteres de nome de usuário, consulte IADsOpenDSObject::OpenDSObject. Se não for especificado, o padrão será o usuário conectado ou o usuário representado pelo processo de chamada.
"Password"	Uma cadeia de caracteres que especifica a senha do usuário identificado por "ID do usuário".
"Criptografar senha"	Um valor booleano que especifica se a senha é criptografada. O padrão é false.
"Bandeira ADSI"	Um conjunto de sinalizadores da enumeração ADS_AUTHENTICATION_ENUM que especificam as opções de autenticação de associação. O padrão é zero.

O exemplo de código a seguir mostra como as propriedades são definidas antes de criar o objeto Command .

Set oConnect = CreateObject("ADODB.Connection")
oConnect.Provider = "ADsDSOObject"
oConnect.Properties("User ID") = stUser
oConnect.Properties("Password") = stPass
oConnect.Properties("Encrypt Password") = True
oConnect.Open "DS Query", stUser, stPass

O segundo objeto ADO é o objeto Command . O ProgID do objeto Command é "ADODB. Comando". Esse objeto permite que você emita instruções de consulta e outros comandos para ADSI usando a conexão ativa. O objeto Command usa sua propriedade ActiveConnection para manter uma conexão ativa. Ele também mantém a propriedade CommandText para manter instruções de consulta emitidas por um usuário. As instruções de consulta são expressas no dialeto SQL ou no dialeto LDAP.

Os exemplos de código a seguir mostram como criar um objeto Command .

Set command = CreateObject("ADODB.Command")
Set command.ActiveConnection = oConnect
command.CommandText = 
"SELECT AdsPath, cn FROM 'LDAP://DC=Fabrikam,DC=com' WHERE objectClass = '*'"

No exemplo de código a seguir, inclua a biblioteca de tipos ADO (msadoXX.dll) como uma das referências.

Dim command As New Command
Set command.ActiveConnection = oConnect
command.CommandText = "<LDAP://DC=Fabrikam,DC=com>;(objectClass=*);AdsPath, cn; subTree"

As opções de pesquisa para o objeto Command são especificadas definindo a propriedade Properties . A tabela a seguir lista as propriedades nomeadas aceitáveis para Propriedades.

Propriedade nomeada	Descrição
"Assíncrono"	Um valor booleano que especifica se a pesquisa é síncrona ou assíncrona. O padrão é False (síncrono). Uma pesquisa síncrona bloqueia até que o servidor retorne o resultado inteiro ou, para uma pesquisa paginada, a página inteira. Uma pesquisa assíncrona bloqueia até que uma linha dos resultados da pesquisa esteja disponível ou até que o tempo especificado pela propriedade "Timeout" decorra.
"Resultados do cache"	Um valor booleano que especifica se o resultado deve ser armazenado em cache no lado do cliente. O padrão é true; O ADSI armazena em cache o conjunto de resultados. Desativar essa opção pode ser desejável para grandes conjuntos de resultados.
"Perseguir referências"	Um valor do ADS_CHASE_REFERRALS_ENUM que especifica como a pesquisa persegue referências. O padrão é ADS_CHASE_REFERRALS_NEVER. Para obter mais informações sobre essa propriedade, consulte Referências.
"Somente nomes de coluna"	Um valor booleano que indica que a pesquisa deve recuperar apenas o nome dos atributos aos quais os valores foram atribuídos. O padrão é false.
"Apelidos de deref"	Um valor booleano que especifica se os aliases de objetos encontrados são resolvidos. O padrão é false.
"Tamanho da página"	Um valor inteiro que ativa a paginação e especifica o número máximo de objetos a serem retornados em um conjunto de resultados. O padrão é nenhum tamanho de página. Para obter mais informações, consulte Recuperando grandes conjuntos de resultados.
"SearchScope"	Um valor da enumeração ADS_SCOPEENUM que especifica o escopo de pesquisa. O padrão é ADS_SCOPE_SUBTREE.
"Limite de tamanho"	Um valor inteiro que especifica o limite de tamanho para a pesquisa. Para o Active Directory, o limite de tamanho especifica o número máximo de objetos retornados. O servidor pára de pesquisar quando o limite de tamanho é atingido e retorna os resultados acumulados. O padrão é sem limite.
"Classificar"	Uma cadeia de caracteres que especifica uma lista separada por vírgulas de atributos a serem usados como chaves de classificação. Essa propriedade funciona apenas para servidores de diretório que oferecem suporte ao controle LDAP para classificação do lado do servidor. O Active Directory oferece suporte ao controle de classificação, mas pode afetar o desempenho do servidor, especialmente se o conjunto de resultados for grande. Lembre-se de que o Active Directory oferece suporte a apenas uma única chave de classificação. O padrão é nenhuma classificação.
"Limite de tempo"	Um valor inteiro que especifica o limite de tempo, em segundos, para a pesquisa. Quando o limite de tempo é atingido, o servidor pára de pesquisar e retorna os resultados acumulados. O padrão é sem limite de tempo.
"Tempo limite"	Um valor inteiro que especifica o valor de tempo limite do lado do cliente, em segundos. Esse valor indica o tempo que o cliente aguarda os resultados do servidor antes de interromper a pesquisa. O padrão é sem tempo limite.

O exemplo de código a seguir mostra como definir opções de pesquisa.

Const ADS_SCOPE_ONELEVEL = 1
Const ADS_CHASE_REFERRALS_EXTERNAL = &H40

Dim Com As New Command
 
Com.Properties("Page Size") = 999
Com.Properties("Timeout") = 30     ' Seconds
Com.Properties("searchscope") = ADS_SCOPE_ONELEVEL
Com.Properties("Chase referrals") = ADS_CHASE_REFERRALS_EXTERNAL
Com.Properties("Cache Results") = False     ' Do not cache the result set.

O terceiro objeto ADO é RecordSet. Você obtém esse objeto quando você invoca o método Execute em um objeto Command . A função principal do objeto RecordSet é enumerar o conjunto de resultados e obter os dados. O conjunto de resultados pode conter valores para atributos que têm valores únicos ou múltiplos. Obter um atributo de valor único é simples, semelhante a obter o valor da coluna no banco de dados relacional, por exemplo:

Fields('name').Value

Obter um atributo com vários valores, no entanto, é mais desafiador. Nesse caso, o Field.Value é uma matriz e você deve verificar o limite inferior e superior da matriz, conforme mostrado no exemplo de código a seguir.

Set rs = Com.Execute
 
For i = 0 To rs.Fields.Count - 1
    Debug.Print rs.Fields(i).Name, rs.Fields(i).Type
Next i
 
'--------------------------
' Navigate the record set.
'--------------------------
rs.MoveFirst
lstResult.Clear      ' Clear the user interface.
While Not rs.EOF
For i = 0 To rs.Fields.Count - 1
    ' For Multi Value attribute
    If rs.Fields(i).Type = adVariant And Not (IsNull(rs.Fields(i).Value)) Then
        Debug.Print rs.Fields(i).Name, " = "
        For j = LBound(rs.Fields(i).Value) To UBound(rs.Fields(i).Value)
            Debug.Print rs.Fields(i).Value(j), " # "
            lstResult.AddItem rs.Fields(i).Value(j)
        Next j
    Else
        ' For Single Value attribute.
         Debug.Print rs.Fields(i).Name, " = ", rs.Fields(i).Value
         lstResult.AddItem rs.Fields(i).Value
    End If
Next i
rs.MoveNext
Wend

O exemplo de código a seguir desabilita as contas de usuário em um servidor LDAP.

Dim X as IADs
Dim con As New Connection, rs As New Recordset
Dim MyUser As IADsUser
 
con.Provider = "ADsDSOObject"
con.Open "Active Directory Provider", "CN=Test,CN=Users,DC=Fabrikam,DC=COM,O=INTERNET", "Password"
Set rs = con.Execute("<LDAP://MyMachine/DC=MyDomain,DC=Fabrikam,DC=com>;(objectClass=User);ADsPath;onelevel")
 
While Not rs.EOF
    ' Bind to the object to make changes 
    ' to it because ADO is currently read-only.
    MyUser = GetObject(rs.Fields(0).Value)
    MyUser.AccountDisabled = True
    MyUser.SetInfo
    rs.MoveNext
Wend

Para obter mais informações sobre o modelo de objeto ADO, consulte Microsoft ActiveX Data Objects.