Click here to Skip to main content
Click here to Skip to main content

Querying Active Directory using .NET classes and LDAP queries

, 30 May 2003
Rate this:
Please Sign up or sign in to vote.
A tutorial describing how to query Windows Active Directory to retrieve different objects using classes defined under .NET DirectoryServices namespace and LDAP queries

Sample Image - ActiveDirQueryDemo.jpg

Introduction

This article describes how to use .NET framework to manage resources under Windows Active Directory Services. Microsoft provides ADSI (Active Directory Services Interface) which can interact with many providers including IIS (Internet Information Services), LDAP (Lightweight Directory Access Protocol), WinNT and NDS (Novell Netware Directory Service).
Since my aim is to demonstrate the usage of .NET DirectoryService classes I am restricting the demo project to querying some commonly used resources (computers, users and printers) in the domain where the user's machine is, at the same time demonstrating the power of Active Directory services and the ease with which Active Directory objects can be retrieved.

I have also used LDAP in this demo since I thought that it will be useful to know this protocol as it is a platform independent protocol.

There are different ways to query the Active Directory Services in a C# program

  • using the ADSI through COM Interop. For this, in the Visual Studio C# project go to "Add References..." and select the COM tab and select Active DS Type Library from the list. Add using ActiveDs; statement to the top of your file or use fully qualified class names to access ADSI functions.
  • Using the Active Directory Services OleDB Provider (ADsDSOObject). This approach is mostly useful to add Active Directory as a linked server in SQL Server. This subject is out of scope for the present article, I will discuss how to query Active Directory using the ADS OleDB provider in a different article.
  • Using the classes provided under .NET System.DirectoryServices namespace. To access these classes add System.DirectoryServices.dll to the references. This article demonstrates this approach.

.NET System.DirectoryServices namespace

The System.DirectoryServices namespaces provides two important classes DirectoryEntry and DirectorySearcher to work with the Active Directory. The DirectoryEntry class represents a resource in the Active Directory and the DirectorySearcher class is used to query the Active Directory. The other classes under this namespace are for .NET security and collection classes to support the above said main classes.
You have to add System.DirectoryServices to your references by selecting System.DirectoryServices.dll from .NET tab in the Add Reference dialog box.

LDAP format filter strings

The DirectorySearcher class uses a search root which is a server where the search begins and a LDAP filter string (which is analogous to where clause in SQL) to query the Active Directory resources. LDAP format filter strings are similar to LISP. A condition is enclosed by parenthesis and an operator precedes 2 conditions. Eg. (& (A)(B)) The statement is equivalent to saying A and B. Remember the parenthesis. Another example (| (& (A)(B) ) (C) ) should be interpreted as (A and B) or (C).

The OLAP conditional statements are formed by using Active Directory attributes like name, objectCategory, objectClass, printerName, ListedName etc. For eg. to query for a list of printers the condition would be (objectCategory=printQueue) where objectCategory is an attribute and printQueue is the value expected to be assigned to a printer resource in Active Directory. Similary to query for all printers which start with a character 'G' the LDAP query would be (& (objectCategory=printQueue) (name=G*) ) In the above filter observe that the values do not have quotes (' or ") around them.

Using the code

The demo project demonstrates how to query the Active Directory Services and fetch different objects. The LDAP queries and the usage of .NET classes used are confined to QueryObjectsByNETClasses() and GetFilterString() methods.

The following code in QueryObjectsByNETClasses() method creates a DirectorySearcher object and sets properties on the searcher depending on the user preferences given in the main form. The description of different properties is in the comments in the code. Only "name" is added to the PropertiesToLoad property of DirectorySearcher class to save time as we are only interested in retrieving name and objectClass for the list of objects returned.

    DirectorySearcher ds = new DirectorySearcher();
    ds.SearchRoot = new DirectoryEntry("");    
      // start searching from local domain
    ds.Filter = GetFilterString();        
      // get the LDAP filter string based on selections on the form
    ds.PropertyNamesOnly = true;        
      // this will get names of only those 
      // properties to which a value is set
    ds.PropertiesToLoad.Add("name");

    // (PageSize) Maximum number of objects 
    // the server will return per page
    // in a paged search. Default is 0, i.e. no paged search
    if (ObjsPerPage.Text.Length > 0) 
        ds.PageSize = Int32.Parse(ObjsPerPage.Text);

    // (ServerPageTimeLimit) the amount of time the server
    // should observe to search a page of results
    // default is -1, i.e. search indefinitely
    if (PageTimeLimit.Text.Length > 0) 
        ds.ServerPageTimeLimit = new TimeSpan((long)(Decimal.Parse(
            PageTimeLimit.Text) * TimeSpan.TicksPerSecond));

    // (SizeLimit) maximum number of objects the server 
    // returns in a search
    // default is 0 - interpreted as server 
    // set default limit of 1000 entries
    if (ObjsToFetch.Text.Length > 0) 
        ds.SizeLimit = Int32.Parse(ObjsToFetch.Text);

    // (ServerTimeLimit) amount of time that the server 
    // should observe in a search
    // default is -1 interpreted as server default limit of 120 seconds 
    if (TotalTimeLimit.Text.Length > 0) 
        ds.ServerTimeLimit = new TimeSpan((long)(Decimal.Parse(
           TotalTimeLimit.Text) * TimeSpan.TicksPerSecond));

    // (SearchScope) option to search one level or complete subtree
    // default is Subtree, so set this option only if oneLevel is selected
    if (searchOptionCB.SelectedIndex == 1)
        ds.SearchScope = SearchScope.OneLevel;

    // (CacheResults) property by default is true
    ds.CacheResults = CacheResultsCB.Checked;

    ds.ReferralChasing = ReferralChasingOption.None;

    if (SortResultsCB.Checked)
        ds.Sort = new SortOption("name", SortDirection.Ascending);

The FormFilter() and GetFilterString() functions are used to form the LDAP query strings (see the explaination for the format of these strings in the LDAP format filter strings section above). Mainly observe the placement of & and | operators before the lists. For a complete set of attributes on which the queries can be formed for different objects refer to the Active Directory Schema under MSDN here.

    // form a filter string for the search in LDAP format
    private string FormFilter(string objectCategory, string filter)
    {
        String result;
        result = String.Format("(&(objectCategory={0})(name={1}))", 
           objectCategory, filter);
        return result;
    }

    // this function forms the filter string based on the selected
    // objects on the form
    private string GetFilterString()
    {
        // form the filter string for directory search
        string filter = "";
        if (UsersCB.Checked)
            filter += FormFilter("user", UsersFilter.Text);
        if (ComputersCB.Checked)
            filter += FormFilter("computer", ComputersFilter.Text);
        if (PrintersCB.Checked)
            filter += FormFilter("printQueue", PrintersFilter.Text);

        // add all the above filter strings
        return "(|" + filter + ")";
    }

Important Points and Notes

  • Use objectCategory attribute instead of objectClass where ever possible. Active Directory documentation mentions two things related to this issue :
    • objectClass attribute can have multiple values. This can be a problem especially if you are retriving objectClass. You can end up with multiple values !
    • objectCategory is an indexed attribute in Active Directory. So using objectCategory speeds up queries.

The second point is more important because all the examples given in MSDN use objectClass, whereas using objectCategory will speed up queries !

  • If the list queried is too large then there is a possibility of a timeout. So don't be surprised if your query does not return the complete list. A point to be noted is that you cannot set a value to ServerTimeLimit larger than the default value of 120 seconds ! So if you are looking for all objects and your directory is too large it is better to query number of times by changing your LDAP filter string incrementally (for eg. a*, b* ..) and combining the results.
  • Try to use PropertiesToLoad and PropertyNamesOnly properties of DirectorySearcher if you know what properties you are trying to retrieve. If PropertyNamesOnly is set to true, the query will fetch the names of only those properties for which a value is set. Giving names of properties to be loaded to PropertiesToLoad will reduce the fetch time. By default PropertiesToLoad is set to an empty StringCollection to fetch all the properties, and PropertyNamesOnly is set to false to retrieve all properties' names even if a value is not set. For eg. in my demo I have given "name" property to be loaded and set PropertyNamesOnly to true. Please note that even if not specified objectClass and objectCategory propertied are automatically loaded whenever an object is fetched.
  • By default all the results of a Active Directory fetch are cached. Set the CacheResults property of DirectorySearcher to false to refresh the object cache on the local computer.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

About the Author

Sriram Chitturi
Architect
United States United States
No Biography provided

Comments and Discussions

 
Questioncomment Pinmemberpatamaporn23-Jan-13 16:12 
GeneralMy vote of 5 PinmemberSavindraSingh11-Jan-13 1:49 
QuestionMSLDAP. Pinmembermacupryk6-Oct-11 4:18 
Do you guys know where I can get some code to connect to msldap?
GeneralThanks Sriram Pinmemberanurag842514-Oct-10 9:22 
GeneralMy vote of 5 PinmemberWhy .NET12-Oct-10 19:12 
QuestionBasic design fault? PinmemberRenniePet12-Jan-10 7:07 
AnswerRe: Basic design fault? Pinmemberizogi9-May-10 16:52 
QuestionVersion for Visual Studio 08 Pinmembertbark27-Jan-09 15:55 
JokeRe: Version for Visual Studio 08 PinmemberCoderGirl4226-Mar-09 12:15 
AnswerRe: Version for Visual Studio 08 PinmemberRenniePet12-Jan-10 6:37 
QuestionHow to get other information of the user Pinmemberdabuskol2-Dec-08 20:49 
GeneralUser Creation Help Required (mukatys@yahoo.com) PinmemberAsif Mukaty17-Jun-08 20:38 
GeneralSolution for other LDAP servers Pinmemberwojtekp22-Feb-08 19:53 
GeneralCan't open it b/c it says I have the wrong .Net runtime version Pinmemberbort198327-Jul-07 10:02 
GeneralActive computers PinmemberMubshir Raza Ali6-Jul-07 2:18 
GeneralNested groups PinmemberRefky Wahib2-Apr-07 23:02 
Questionldap filter size Pinmembersiedell12-Dec-06 10:14 
GeneralExcelente! (Great!) Pinmembergoarango27-Nov-06 9:04 
GeneralThank you Sriram! Pinmemberssudhaa7-Nov-06 6:25 
QuestionHow I can get a good list of attributes and filter criteria? PinmemberWilliam Yeung10-Oct-06 1:09 
AnswerRe: How I can get a good list of attributes and filter criteria? PinmemberDuoc BT26-Oct-06 13:54 
GeneralDelete user AD [modified] PinmemberBigbirdtung6-Jun-06 0:33 
GeneralCan't conect to DC from LAN PinmemberBigbirdtung6-Jun-06 0:15 
AnswerRe: Can't conect to DC from LAN Pinmemberzohaibabrar22-Sep-06 22:35 
GeneralSize Limit Pinmembercavedog65-Jun-06 5:06 
GeneralRe: Size Limit Pinmemberandreas.eppinger26-Jun-06 23:39 
GeneralRe: Size Limit PinmemberMarlon Rodriguez20-Jul-06 16:46 
GeneralRe: Size Limit Pinmemberjportelas29-Jan-07 7:41 
AnswerRe: Size Limit Pinmemberandreas.eppinger29-Jan-07 9:55 
GeneralRe: Size Limit Pinmemberjportelas30-Jan-07 2:28 
GeneralLDAP Query for Groups in Active Directory Pinmemberchitransh2-Jun-06 0:43 
AnswerRe: LDAP Query for Groups in Active Directory Pinmembervinodjnair25-Sep-06 23:59 
GeneralRe: LDAP Query for Groups in Active Directory Pinmembersoup198318-Dec-06 9:18 
GeneralRe: LDAP Query for Groups in Active Directory PinmemberThomas Guilbault21-Dec-06 12:45 
Questionhow to write LDAP querries Pinmemberkrsuman190910-May-06 0:45 
Questionhow do i get deleted computers from AD Pinmemberiam_Aravind27-Apr-06 8:48 
GeneralQuerying AD from Mono on Red Hat PinmemberGerryTheBastard23-Mar-06 12:55 
Question? Can I access LDAP of Solaris environment from my Windows environment. PinmemberSuranjan Nandi8-Mar-06 23:00 
AnswerRe: ? Can I access LDAP of Solaris environment from my Windows environment. Pinmemberkarampu2-Apr-06 18:08 
GeneralCan't connect to AD PinmemberGireesha813-Mar-06 1:16 
Generalgetting the list of domains PinmemberThe real Vitya28-Feb-06 3:18 
GeneralRe: getting the list of domains PinmemberSriram Chitturi28-Feb-06 4:23 
GeneralRe: getting the list of domains PinmemberThe real Vitya28-Feb-06 4:41 
QuestionRe: getting the list of domains Pinmemberthund3rstruck22-Feb-07 5:32 
GeneralGREATE!!!!!! Pinmembermrmubi22-Feb-06 23:19 
GeneralQuery Group Membership PinmemberJCOUSNEHA16-Feb-06 7:52 
GeneralGetting User Group Info from Active Directory using LDAP PinmemberSAPAN DESAI4-May-05 5:11 
GeneralRe: Getting User Group Info from Active Directory using LDAP PinmemberWuzac29-Mar-06 22:25 
QuestionHow to query for groups in AD PinmemberInala13-Feb-05 1:39 
GeneralDo you know AD's Global Catalog PinmemberLehi6-Jan-05 12:22 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140721.1 | Last Updated 31 May 2003
Article Copyright 2003 by Sriram Chitturi
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid