Searching the Directory

The most common directory task is searching. While the DirectoryEntry object can be used to for simple searches, such as finding a single directory object that is required for a simple operation such as binding to the domain, it cannot conduct complex searches or return large sets of results.

To add a robust search operation to your application, use the DirectorySearcher object. The DirectorySearcher object provides a set of properties and methods that enable you to select multiple search criteria, such as a search scope, filters, wildcard strings, page sizes for result sets, and sorting.

This section includes the following topics:

• Search Size and Page Size
• Getting Search Results
• Setting the Search Scope
• Setting Search Filters
• Additional Search Options
• DirectorySearcher Example

Before you perform a search, you must be familiar with the DirectorySearcher object and directory search concepts. If you previously used ADSI, then you might have used the IDirectorySearch COM interface. The DirectorySearcher object is a wrapper for IDirectorySearch. For more information about this interface, see the topic IDirectorySearch in the MSDN Library at https://go.microsoft.com/fwlink/?LinkID=27252.

To perform a search, your application must first bind to a root point in the directory. For optimal performance, select a point that will provide the smallest result set. Configure DirectorySearcher to provide the following parameters for your search operation:

• A search filter that narrows the search to a specific type of object
• A scope of objects to search
• A list of attributes to return with the object

When you configure this search, you must decide which type of object to search for, and then create a search filter for that type of object. The DirectorySearcher object provides a Filter property that requires a string that uses LDAP syntax as the filter string.

Next, you must decide whether the scope of the filter should be at the base of the node that your application is bound to, through one level, or through the subtree. The SearchScope property is used to set this parameter. Finally, you must decide which property names and values to return with the object.

Optionally, you can use a DirectorySynchronization object to perform a directory synchronization search, which enables the application to perform a search, iterate through all results, perform other functions not related to the search, or become inactive for a while. The application will then eventually perform the same search again to retrieve any new results for that search. In this way, an application can keep track of any updates to Active Directory Domain Services that meet the criteria that is specified in the search.

The following diagram illustrates a search that binds to the Sales container.

DirectorySearcher returns a single result and its properties in a SearchResult object. Result sets are returned as a SearchResultCollection, which is a container for all SearchResult objects that are returned by the search.

DirectorySearcher provides the following two methods to perform your search:

• FindOne returns a single item.
• FindAll returns a collection of items.

For more information and a procedure for creating a basic search application, see the topic Searching Active Directory Hierarchies in the MSDN Library at https://go.microsoft.com/fwlink/?LinkID=27252.

See Also

Reference

System.DirectoryServices
DirectoryEntry
DirectorySearcher
SearchScope
DirectorySynchronization

Concepts

Getting Started in System.DirectoryServices

Send comments about this topic to Microsoft.

Copyright © 2007 by Microsoft Corporation. All rights reserved.