Ricerca con oggetti dati ActiveX (ADO)

Il modello ActiveX Data Object (ADO) è costituito da oggetti elencati nella tabella seguente.

Oggetto	Descrizione
Connessione	Connessione aperta a un'origine dati OLE DB, ad esempio ADSI.
Comando	Definisce un comando specifico da eseguire sull'origine dati.
Parametro	Raccolta facoltativa per i parametri da fornire all'oggetto comando.
Recordset	Set di record da una tabella, un oggetto comando o una sintassi SQL. È possibile creare un recordset senza alcun oggetto connessione sottostante.
Campo	Singola colonna di dati in un recordset.
Proprietà	Raccolta di valori forniti dal provider per ADO.
Errore	Contiene dati sugli errori di accesso ai dati. Aggiornato quando si verifica un errore in una singola operazione.

Affinché ADO comunichi con ADSI, devono essere presenti almeno due oggetti ADO: Connessione ion e RecordSet. Questi oggetti ADO servono rispettivamente per autenticare gli utenti ed enumerare i risultati. In genere, si userà anche un oggetto Command per mantenere una connessione attiva, specificare parametri di query, ad esempio dimensioni della pagina e ambito di ricerca ed eseguire una query. Per altre informazioni sulla sintassi del filtro di ricerca, vedere sintassi del filtro di ricerca.

L'oggetto Connessione ion carica il provider OLE DB e convalida le credenziali utente. In Visual Basic chiamare la funzione CreateObject con "ADODB.Connessioneion" per creare un'istanza di un oggetto Connessione ion e quindi impostare la proprietà Provider dell'oggetto Connessione ion su "ADsDSOObject". "ADODB. Connessione ion" è il ProgID dell'oggetto Connessione ion e "ADsDSOObject" è il nome del provider OLE DB in ADSI. Se non vengono specificate credenziali, vengono usate le credenziali dell'utente attualmente connesso.

Nell'esempio di codice seguente viene illustrato come creare un'istanza di un oggetto Connessione ion.

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

Nell'esempio di codice seguente viene illustrato come creare un'istanza di un oggetto Connessione ion.

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

Nell'esempio di codice seguente viene illustrato come creare un'istanza di un oggetto Connessione ion. Tenere presente che è necessario includere la libreria dei tipi ADO (msadoXX.dll) come uno dei riferimenti nel progetto Visual Basic.

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

Specificare i dati di autenticazione utente impostando le proprietà dell'oggetto Connessione ion. Nella tabella seguente sono elencate le proprietà di autenticazione utente supportate da ADSI.

Proprietà	Descrizione
"ID utente"	Stringa che identifica l'utente il cui contesto di sicurezza viene utilizzato durante l'esecuzione della ricerca. Per altre informazioni sul formato della stringa del nome utente, vedere IADsOpenDSObject::OpenDSObject. Se non specificato, il valore predefinito è l'utente connesso o l'utente rappresentato dal processo chiamante.
"Password"	Stringa che specifica la password dell'utente identificato da "ID utente".
"Crittografa password"	Valore booleano che specifica se la password è crittografata. L'impostazione predefinita è false.
"Flag ADSI"	Set di flag dell'enumerazione ADS_AUTHENTICATION_ENUM che specificano le opzioni di autenticazione dell'associazione. Il valore predefinito è zero.

Nell'esempio di codice seguente viene illustrato come vengono impostate le proprietà prima di creare l'oggetto 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

Il secondo oggetto ADO è l'oggetto Command . Il ProgID dell'oggetto Command è "ADODB. Comando". Questo oggetto consente di eseguire istruzioni di query e altri comandi ad ADSI usando la connessione attiva. L'oggetto Command utilizza la proprietà Active Connessione ion per mantenere una connessione attiva. Gestisce anche la proprietà CommandText per contenere istruzioni di query rilasciate da un utente. Le istruzioni di query sono espresse nel dialetto SQL o nel dialetto LDAP.

Negli esempi di codice seguenti viene illustrato come creare un oggetto Command .

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

Nell'esempio di codice seguente includere la libreria dei tipi ADO (msadoXX.dll) come uno dei riferimenti.

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

Le opzioni di ricerca per l'oggetto Command vengono specificate impostando la proprietà Properties . Nella tabella seguente sono elencate le proprietà denominate accettabili per Proprietà.

Proprietà denominata	Descrizione
"Asincrono"	Valore booleano che specifica se la ricerca è sincrona o asincrona. Il valore predefinito è False (sincrono). Una ricerca sincrona si blocca fino a quando il server non restituisce l'intero risultato o per una ricerca con paging, l'intera pagina. Una ricerca asincrona si blocca fino a quando non è disponibile una riga dei risultati della ricerca o fino al tempo specificato dalla proprietà "Timeout".
"Risultati cache"	Valore booleano che specifica se il risultato deve essere memorizzato nella cache sul lato client. Il valore predefinito è true; ADSI memorizza nella cache il set di risultati. La disattivazione di questa opzione può essere utile per i set di risultati di grandi dimensioni.
"Insegui segnalazioni"	Valore del ADS_CHAedizione Standard_REFERRALS_ENUM che specifica il modo in cui la ricerca insegue i riferimenti. Il valore predefinito è ADS_CHAedizione Standard_REFERRALS_NEVER. Per altre informazioni su questa proprietà, vedere Segnalazioni.
"Solo nomi di colonna"	Valore booleano che indica che la ricerca deve recuperare solo il nome degli attributi a cui sono stati assegnati i valori. L'impostazione predefinita è false.
"Alias deref"	Valore booleano che specifica se gli alias degli oggetti trovati vengono risolti. L'impostazione predefinita è false.
"Dimensioni pagina"	Valore intero che attiva il paging e specifica il numero massimo di oggetti da restituire in un set di risultati. Il valore predefinito non è una dimensione della pagina. Per altre informazioni, vedere Recupero di set di risultati di grandi dimensioni.
"SearchScope"	Valore dell'enumerazione ADS_SCOPedizione Enterprise NUM che specifica l'ambito di ricerca. Il valore predefinito è ADS_SCOPE_SUBTRedizione Enterprise.
"Limite dimensioni"	Valore intero che specifica il limite di dimensioni per la ricerca. Per Active Directory, il limite di dimensioni specifica il numero massimo di oggetti restituiti. Il server interrompe la ricerca quando viene raggiunto il limite di dimensioni e restituisce i risultati accumulati. Il valore predefinito non è un limite.
"Ordina su"	Stringa che specifica un elenco delimitato da virgole di attributi da utilizzare come chiavi di ordinamento. Questa proprietà funziona solo per i server di directory che supportano il controllo LDAP per l'ordinamento lato server. Active Directory supporta il controllo di ordinamento, ma può influire sulle prestazioni del server, in particolare se il set di risultati è di grandi dimensioni. Tenere presente che Active Directory supporta solo una singola chiave di ordinamento. Il valore predefinito non è un ordinamento.
"Limite di tempo"	Valore intero che specifica il limite di tempo, espresso in secondi, per la ricerca. Quando viene raggiunto il limite di tempo, il server interrompe la ricerca e restituisce i risultati accumulati. Il valore predefinito non è alcun limite di tempo.
"Timeout"	Valore intero che specifica il valore di timeout sul lato client, espresso in secondi. Questo valore indica il tempo in cui il client attende i risultati dal server prima di arrestare la ricerca. Il valore predefinito non è timeout.

Nell'esempio di codice seguente viene illustrato come impostare le opzioni di ricerca.

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.

Il terzo oggetto ADO è RecordSet. Questo oggetto viene ottenuto quando si richiama il metodo Execute su un oggetto Command . La funzione primaria dell'oggetto RecordSet consiste nell'enumerare il set di risultati e ottenere i dati. Il set di risultati può contenere valori per gli attributi con valori singoli o multipli. Ottenere un attributo a valore singolo è semplice, simile a ottenere il valore della colonna nel database relazionale, ad esempio:

Fields('name').Value

Ottenere un attributo con più valori, tuttavia, è più complesso. In questo caso, Field.Value è una matrice ed è necessario controllare il limite inferiore e superiore della matrice, come illustrato nell'esempio di codice seguente.

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

Nell'esempio di codice seguente vengono disabilitati gli account utente in un server 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

Per altre informazioni sul modello a oggetti ADO, vedere Microsoft ActiveX Data Objects.