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.