Query by Example

Artikel
09/03/2008

Der QBE-Suchmechanismus (Query by Example) sucht mithilfe eines vorhandenen Objekts nach Objekten in einem Verzeichnis. Um QBE zu verwenden, wird in der Anwendung eine Instanz eines Prinzipalobjekts (Computer, Benutzer oder Gruppe) erstellt und Eigenschaften für das Objekt festgelegt. Dieses Objekt wird das Abfragefilter für die PrincipalSearcher-Klasse. Die FindAll-Methode durchsucht die im Prinzipalkontext angegebene Domäne nach Objekten mit Eigenschaften, die mit den im Abfragefilter festgelegten Eigenschaften übereinstimmen. Die FindAll-Methode gibt alle Objekte zurück, die dem angegebenen Objekt entsprechen. Demgegebenüber gibt die FindOne-Methode

nur ein einziges übereinstimmendes Prinzipalobjekt zurück. Im folgenden Codebeispiel wird ein Prinzipalobjekt für einen Benutzer mit dem Namen Jim Daly und die Domäne nach Benutzer mit demselben Namen durchsucht.

// Create the context for the principal object. 
PrincipalContext ctx = new PrincipalContext(ContextType.Domain, 
                                            "fabrikam",
                                            "DC=fabrikam,DC=com");

// Create an in-memory user object to use as the query example.
UserPrincipal u = new UserPrincipal(ctx);

// Set properties on the user principal object.
u.GivenName = "Jim";
u.Surname = "Daly";

// Create a PrincipalSearcher object to perform the search.
PrincipalSearcher ps = new PrincipalSearcher();

// Tell the PrincipalSearcher what to search for.
ps.QueryFilter = u;

// Run the query. The query locates users 
// that match the supplied user principal object. 
PrincipalSearchResult<Principal> results = ps.FindAll();

Der Typ des an den QBE-Filter übergebenen Objekts bestimmt den Typ des Prinzipalobjekts, das von der Suche zurückgegeben wird. Im Codebeispiel weiter oben in diesem Thema wird von der Anwendung beispielsweise ein UserPrincipal-Objekt erstellt, das als Abfragefilter für die PrincipalSearcher-Klasse verwendet wird. Da es sich beim Abfragefilter um ein UserPrincipal-Objekt handelt, sind alle Objekte, die von der FindAll-Methode zurückgegeben werden, ebenfalls UserPrincipal-Objekte. Wenn für das an den QBE-Filter übergebene Objekt keine Eigenschaften festgelegt wurden, werden alle Speicherobjekte des angegebenen Typs zurückgegeben.

Die durch QBE erstellte Abfrage erzeugt ein logisches UND aller Eigenschaften, die für das Prinzipalobjekt festgelegt wurden. Bei mehrwertigen Attributen entspricht die resultierende Abfrage dem logischen UND aller für das Attribut festgelegten Werte. Die resultierende Abfrage gilt nur für den Speichertyp (Domäne oder Anwendungsverzeichnis), für den die Abfrage ausgeführt wird. Der Code im früheren Beispiel erzeugt beispielsweise die folgende LDAP-Abfrage:

(&(objectCategory=user)(givenName=Jim)(sn=Daly))

Von QBE werden nur nicht referenzielle Eigenschaften unterstützt, d. h. Eigenschaften, bei denen es sich nicht um Verweise handelt. Wenn das Prinzipalobjekt, das in der Abfrage verwendet wird, Eigenschaftenwerte enthält, die Prinzipalobjekte oder Links zu Prinzipalobjekten sind, löst die Abfrage eine InvalidOperationException-Ausnahme aus. Beispiel: Für ein Gruppenobjekt sind die Eigenschaften für Anzeigename und Beschreibung festgelegt. Da diese Eigenschaften nicht referenzielle Eigenschaften sind, h. d. keine anderen Prinzipalobjekte sind oder mit anderen Prinzipalobjekten verknüpft sind, wird der Aufruf von FindAll oder FindOne erfolgreich ausgeführt. Wenn das Gruppenobjekt einen Member, z. B. ein UserPrincipal-Objekt hinzufüget, wird beim Aufruf von FindAll oder FindOne eine Ausnahme ausgelöst.

Festlegen einer nicht referenziellen Eigenschaft

Im folgenden Codebeispiel wird eine einfache QBE-Abfrage veranschaulicht, in der für das Gruppenobjekt keine referenziellen Eigenschaften festgelegt werden. In diesem Fall wird die Abfrage erfolgreich ausgeführt, und die Ergebnisse enthalten alle übereinstimmenden Gruppenprinzipalobjekte.

// Create the princiapl context for the group object
PrincipalContext ctx = new PrincipalContext(ContextType.Domain);

// Create the GroupPrincipal object and set the diplay name property. 
GroupPrincipal g = new GroupPrincipal(ctx);
g.DisplayName = "Administrators";
  
// Create a PrincipalSearcher object     
PrincipalSearcher ps = new PrincipalSearcher(g);

// Searches for all groups named "Administrators" PrincipalSearchResult<Principal> results = ps.FindAll();

Festlegen von referenziellen und nicht referenziellen Eigenschaften

Im folgenden Beispiel wird das Festlegen einer referenziellen Eigenschaft für das Gruppenobjekt veranschaulicht. In diesem Fall schlägt das Codebeispiel mit einer InvalidOperationException-Ausnahme fehl.

// Create the principal context for the group object.
PrincipalContext ctx = new PrincipalContext(ContextType.Domain);

// Create the GroupPrincipal object and set the diplay name property. 
GroupPrincipal g = new GroupPrincipal(ctx);
g.DisplayName = "Administrators";

// Create a new user and add it to the group. 
UserPrincipal u = new UserPrincipal(ctx);
u.GivenName = "Jim";
g.Members.Add(u);// This sets a referential property. 

// Create a PrincipalSearcher object.
PrincipalSearcher ps = new PrincipalSearcher(g);

// An exception is thrown on this call. 
PrincipalSearchResult<Principal> fr = ps.FindAll();

Verwenden von erweiterten Suchfiltern für schreibgeschützte Eigenschaften

Einige Eigenschaften des Prinzipalobjekts sind schreibgeschützte Eigenschaften ("LastLogonTime", "BadLogonCount", "LastBadPasswordAttempt"), da eine programmgesteuerte Bearbeitung dieser Eigenschaften keinen Sinn macht. Daher ist es nicht möglich, ein Prinzipalobjekt als Abfragefilter für diese Eigenschaften zu erstellen. Verwenden Sie in diesen Fällen die AdvancedSearchFilter-Klasse. Der Zugriff auf das entsprechende AdvancedSearchFilter-Objekt eines Prinzipals erfolgt über die AdvancedSearchFilter-Eigenschaft des jeweiligen Prinzipalobjekts. Die Funktionalität von AdvancedSearchFilter bietet mehr Möglichkeiten als nur eine Suche von Übereinstimmungen, wie z. B. die Verwendung einer Größer-als-/Kleiner-als-Logik oder Teilübereinstimmungen. Im folgenden Beispiel wird veranschaulicht, wie mit einem AdvancedFilter-Objekt nach Benutzern gesucht wird, die sich am gestrigen Tag angemeldet haben:

// Create the principal context for the usr object.
PrincipalContext ctx = new PrincipalContext(ContextType.Domain, "fabrikam.com", "CN=Users,DC=fabrikam,DC=com", "administrator", "securelyStoredPassword");

// Create the principal user object from the context
UserPrincipal usr = new UserPrincipal(ctx);
usr.AdvancedSearchFilter.LastLogonTime(DateTime.Now, MatchType.LessThan); 
usr.AdvancedSearchFilter.LastLogonTime(DateTime.Yesterday, MatchType.GreaterThan);

// Create a PrincipalSearcher object.
PrincipalSearcher ps = new PrincipalSearcher(usr);
PrincipalSearchResult<Principal> fr = ps.FindAll();
foreach (UserPrincipal u in results)
        {
            Console.WriteLine(u.Name);
        }

Siehe auch

Referenz

System.DirectoryServices.AccountManagement

Konzepte

Informationen zu System.DirectoryServices.AccountManagement
Verwenden von System.DirectoryServices.AccountManagement

Send comments about this topic to Microsoft.