.Net and Directory Services Programming

.Net Directory Services Programming - C# - Part 3

Michael J. Hamilton, Sr. — Sat, 10 Nov 2007 14:45:41 GMT

.Net Directory Services Programming – C# - Part 3

Topics

DirectorySearcher – the other critical class in the DirectoryServices namespace.

Review

Because a lot of your Directory Services (DS) development will involve querying DS for data, it makes sense that this is a powerful class offered in the namespace, and below are some of the features:

DirectorySearcher – Performs the initial queries against AD
SearchResult – A single object reference from a search performed by DirectorySearcher
ResultPropertyCollection – A collection of properties of the SearchResult instance
ResultPropertyValueCollection – The values of properties in a SearchResult instance.
SearchResultCollection – Basically a collection of SearchResult instances returned from a query by DirectorySearcher
SortOption – Allows a means to sort a result set.

We have briefly touched on DS by introducing some basic DirectoryEntry information and a couple simple examples, and we have introduced some basic properties and examples on how to interact with those.

I have not taken a lot of time to review a directory structure – basically assuming that you should have some of this understanding already. As I delve into the next lesson, this assumption holds fast. If you have any issues or are dealing with something that I am not elaborating enough on, please feel free to email me directly at (mikeh AT thedataworks.net) and I will respond as quickly as I can. Please forgive the notation there – but we all are familiar with the latest in SPAM bots and whatnot.

Show me the Money!!!

Or at least the code. Lets get started…

Parent – Child Relationships

DirectoryEntry objects (DE’s) can be a root object in AD, or an object within another – hence, a child object of another. We reviewed in Part 1 a few of the common references to object types (CN, OU, DC). These are the most prevalent you will deal with.

DC is the root level context. OU’s can be off the root, or a child of other OU’s and even Containers. CN’s can be off the root, within OU’s and often are found within Containers.

A word about Containers and Security

When planning your DS application, keep this in mind: Containers are non-secure objects! Let me explain. AD security is multi-faceted, yes, but the real security is managed using Group Policy (something we are not going to review here).

Containers are basically folders in your directory tree. AD comes with a couple by default. If you promote a server and check your directory tree, you’ll find a Users, a Built-In, and a couple other folders off the root tree (or context/server name) object. These are not OU’s – they are containers.

Group Policy (GP) cannot be applied to a Container object in AD. You can apply GP to objects within Containers – depending on what those objects are – but not the Container itself. This is important because a lot of administration can be simplified by applying the GP to the entire Container. So if not the Container, then what? Organizational Units – OU’s. Alas, OU’s are going to be your preferred folder or container (for lack of a better way to put it) for object storage.

Basic Searches

In Part 1 we introduced a server name and basic OU’s. To re-cap that:

Server: developer.hamilton.com

OU=Accounts – off the root of developer.hamilton.com

OU=Developers – within the OU=Accounts

CN=Mike Hamilton – within the OU=Developers

Within the OU=Accounts I might also create service accounts – basic user accounts that are used to run services such as IIS Application Pools, SQL Server, or other server / service applications. I might also have OU’s that represent other departments that pertain to development: BA’s for the Business Analyst, QA’s, etc. You can nest OU’s and accounts in just about any way you want to. NOTE: In AD – if you have not already – you will run into one of the inherent limitations of the AD Users & Computers (dsa.msc) snap-in: It can only display the first 2,000 objects within a Container or OU. So if you anticipate a large volume of users for a system you are designing, keep this in mind. You will want to present 1) a more suitable customized user interface piece for administration of this DS, or 2) design your object hierarchy so that users are more spread out within the DS. I will touch base on this topic in a later Part and introduce a couple ideas for addressing this limitation.

DirectorySearcher and the SearchResult

When using the DirectorySearcher class, you have the FindOne() and FindAll() methods that build your result set. As they infer, one finds one occurrence, the other finds all occurrences.

Let’s say I had more than one Mike on my team, and I wanted to find all entries that began with Mike?

DirectoryEntry rootEntry = new DirectoryEntry(); // Binds root context

// Now find every CN that has Mike at the beginning of the name…

DirectorySearcher searcherResults = new DirectorySearcher(rootEntry,”(CN=Mike*)”);

This is a simple example, and the result set will be one or more object references that begin with Mike. Notice that I did a bind on the root of the DS. I could have narrowed the focus of the search to only the developer’s OU by doing the following:

DirectoryEntry developersEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer,DC=hamilton,DC=com”);

This would return an entry object where the parent would be the OU=Developers, and not the default root of the DS tree.

Lets say my DS was structured like the following:

developer.hamilton.com à root of the DS

OU=Accounts à First OU of accounts of users.

OU=Developers à Key development personnel

OU=Bas à Business Analyst

OU=QA à Quality Assurance / Test personnel

OU=Users à General users on this server.

Now, we want to find all users that are in the Users OU, not returning the developers or other personnel within the directory. That’s pretty straight forward.

DirectoryEntry developersEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Users,DC=developer,DC=hamilton,DC=com”);

// Now return all users in this OU…

DirectorySearcher searcherResults = new DirectorySearcher(rootEntry,”(CN= *)”);

As you get more familiar with DS programming, you will find there are other ways to accomplish the same result – I am simply trying to open those doors for you.

It is important that you understand how to narrow your search filter in this way because you will find it greatly improves the performance of your application when you know where to search for content and you keep your search filter narrowly defined. For example, if I have 15,000 employees, they would very likely be grouped in AD by their department, and possibly further grouped by sub-departments. I would want to know this information beforehand so I can plan my DS application to be as efficient as possible. I would not want to search the rootDSE each time for a given employee or group of employees, if I know the departments those employees are in.

More on the Search Filter

The filter is a LDAP string that allows you to search for objects based on specific criteria. You will also use relational operators to better refine your search. The following list those operators:

= Equal to

~= Is approximately equal to (or like)

<= Less than or equal to

>= Greater than or equal to

NOTE: You cannot use ‘<’ or ‘>’ individually in LDAP – you must use the notation <= or >=.

The * character works as a wildcard in your search, as in the example above we searched for CN=Mike* or CN=* - in this case, get all Canonical (common) Names beginning with Mike, or get all names period (respectively).

To find all users with a surname of Hamilton you would use

(sn = Hamilton)

To find all users where the email ends in @hamilton.com

(&(objectCategory = person) (objectClass = user) (mail = *@hamilton.com))

Notice the Polish notation used here – the operator comes before the condition. LDAP uses this notation in the Filter. The above example would be more familiar possibly as

(objectCategory = person) AND (objectClass = user) AND (mail = *@hamilton.com)

The following are allowed logical operators:

& AND

| OR

! NOT

You set the filter for a search using the DirectorySearcher.Filter property. The following code will create a binding to the root context, and return everything from the root down:

DirectoryEntry rootEntry = new DirectoryEntry(); // Binds root context

DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry);

Let’s say we have a binding to the rootDSE as above, but only want to return all users with a surname of Hamilton? Change the DirectorySearcher to the following:

DirectorySearcher rootSearcher = new DirectorySearcher(“(sn=Hamilton)”);

You can either pass the DirectoryEntry object, or you can specify a filter in this fashion when creating a DirectorySearcher instance.

Loading Specific Properties

By default, when you create a DirectorySearcher instance, you return all properties for that binding (which can be a lot of data if you have a lot of items in your returned result set).

You can refine your result set by specifying the exact properties to be returned. This is especially important when you could be returning large collections of users.

Following the above example I could create my rootSearcher and then do:

rootSearcher.PropertiesToLoad.Add(“name”);

rootSearcher.PropertiesToLoad.Add(“sn”);

rootSearcher.PropertiesToLoad.Add(“mail”);

rootSearcher.PropertiesToLoad.Add(“telephoneNumber”);

Here I have specifically limited the result set to only include the name, sn (surname), mail and telephoneNumber properties.

Finally, when we define our searcher, we can stipulate the search scope.

Search Scope

The search scope determines the extent of the search in a directory, defaulting to beginning at the root.

In the System.DirectoryServices.SearchScope you will find the following 3 enumerations specified:

Base – Limits the scope to the base, or only 1 object.

OneLevel – Searches 1 level of the immediate child objects, excluding the base object.

Subtree – Searches all child objects under the base object, including the base object.

When creating a DirectorySearcher instance, the following table lists default constructor behaviors:

PROPERTY	DEFAULT VALUE	DESCRIPTION
SearchRoot	Null	Searches the root of the domain controller (rootDSE).
Filter	(objectClass=*)	The search retrieves all objects.
PropertiesToLoad	An empty string array	The search retrieves all properties.
SearchScope	Subtree	The search will be performed on the complete subtree of the base object (or entire domain in this case).

Constructors of the DirectorySearcher Class

The above table displays the default constructor when you create a DirectorySearcher instance like:

DirectoryEntry rootEntry = new DirectoryEntry(); // Binds root context

DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry);

The above specifies the Search Root.

Specifying the Filter Only

We showed this earlier,

DirectorySearcher rootSearcher = new DirectorySearcher(“(sn=Hamilton)”);

Specifying the Search Root and Filter

Create our base / root reference:

DirectoryEntry rootEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer.DC=Hamilton,DC=com”);

// Now specify the filter…

DirectorySearch rootSearcher = new DirectorySearcher(rootEntry, “(sn=Hamilton)”);

Specifying the Filter and a List of Properties to load

// Create the set of properties to load…

string [] searchProperties = new string[4];

searchProperties[0] = “name”;

searchProperties[1] = “sn”;

searchProperties[2] = “mail”;

searchProperties[3] = “telephoneNumber”;

// Get all users that have an email ending in hamilton.com…

DirectorySearcher rootSearcher = new DirectorySearcher(“(mail=*hamilton.com)”, searchProperties);

The above example will return all users from the rootDSE with an email ending in hamilton.com. Let’s refine that.

Specifying the Root, Search Filter, and Properties to Load

// Specify the properties to load… Here we get Full Name, Company, Phone…

string [] searchProperties = new string[3];

searchProperties[0] = “name”;

searchProperties[1] = “co”;

searchProperties[2] = “telephoneNumber”;

// Now bind to a more refined root – developers only…

DirectoryEntry rootEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer,DC=hamilton,DC=com”);

// No get all users from this root with an email ending in hamilton.com…

DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry, “(mail=*hamilton.com)”, searchProperties);

You should have a better idea now how to use the various constructors of the DirectorySearcher class.

Methods of the DirectorySearcher

When you have created a binding and set filter values, you will use 1 of the 2 DirectorySearcher methods:

FindOne() – Returns the first, and only 1 object of the search criteria.

FindAll() – Returns a SearchResultCollection of all objects that matched the search criteria.

We’ll do a brief sample for each method and wrap up this series with the Sorter class.

Return using FindOne()

// The following demonstrates that FindOne() returns only the first entry that matches the search critieria…

DirectoryEntry rootEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer,DC=hamilton,DC=com”);

DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry);

// What to search for…

rootSearcher.Filter = “(CN=*)”;

// Specific properties to load…

rootSearcher.PropertiesToLoad.Add(“name”); // Full name…

rootSearcher.PropertiesToLoad.Add(“mail”); // Primary email addy…

rootSearcher.PropertiesToLoad.Add(“telephoneNumber”); // Phone #...

SearchResult searchResults = rootSearcher.FindOne();

// Extract out the properties returned and display in a console…

ResultPropertyCollection propertiesCollection;

propertiesCollection = searchResults.Properties;

// Cycle through and display (or add to a listbox, etc)…

Foreach (string currentProperty in propertiesCollection.PropertyNames)

{

foreach (Object thisCollection in propertiesCollection[currentProperty])

{

Console.WriteLine(currentProperty + “ = “ + thisCollection);

}

Return using FindAll()

Unlike above, the ResultPropertyCollection being returned with FindOne(), FindAll() comes back in a SearchResultCollection object.

We would process the result set similar to the following:

// Get all objects returned…

foreach (SearchResult searchResults in rootSearcher.FindAll())

{ // Process…

foreach (string propertName in searchResults.Properties.PropertyNames)

{

foreach (Object retEntry in searchResults.Properties[propertyName])

{

Console.WriteLine(propertyName + “ = “ + retEntry);

}

Console.WriteLine(“”);

}

If the root of the search is not properly set, a InvalidOperationException exception will be thrown. Also, if the provider you are trying this against is not supported, a NotSupportedException exception is thrown.

Sorting the Result Sets

Finally, the SortOption class specifies how to sort the result set of a search. The class also allows you to specify either ascending or descending sort order.

Let’s do a search on all users that have an email ending in @hamilton.com and that exist in the Developers OU. Further, restrict the properties returned, sort the list, and using the code snippet above, list the results in a console window.

DirectoryEntry rootEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/OU=Accounts,OU=Developers,DC=developer,DC=hamilton,DC=com”);

DirectorySearcher rootSearcher = new DirectorySearcher(rootEntry);

// Set our search filter and properties to load…

rootSearcher.Filter = “(mail=*hamilton.com)”;

rootSearcher.PropertiesToLoad.Add(“name”); // Full name…

rootSearcher.PropertiesToLoad.Add(“mail”); // Primary email addy…

rootSearcher.PropertiesToLoad.Add(“telephoneNumber”); // Phone #...

// Now sort the result set…

SortOption sortedResults = new SortOption();

sortedResults.PropertyName = “name”; // Sort by full name…

sortedResults.Direction.SortDirection.Ascending;

// Perform the search and output the results..

rootSearcher.Sort = sortedResults;

foreach (SearchResult searchResults in rootSearcher.FindAll())

{ // Process…

foreach (string propertName in searchResults.Properties.PropertyNames)

{

foreach (Object retEntry in searchResults.Properties[propertyName])

{

Console.WriteLine(propertyName + “ = “ + retEntry);

}

Console.WriteLine(“”);

}

Final notes on the following classes: SearchResult, SearchResultCollection, ResultPropertyCollection, and ResultPropertyValueCollection.

The SearchResult class consist of the first entry returned during a search. It retrieves the data from the SearchResultCollection, and the FindOne() method of the DirectorySearcher class returns an instance of the SearchResult class.

The SearchResultCollection class is actually a collection of SearchResult instances and these are returned using the FindAll() method of the DirectorySearcher class. You use the Count property to get the number of items returned in the collection. Use the Item property to index through the SearchResultCollection to enumerate each property. Finally, the PropertiesLoaded property returns a string array containing the names of the properties loaded for the original search criteria.

The ResultPropertyCollection class is accessed as a Properties property of the SearchResult class. It has an Item property you use to index the collection, which is a string value. This index retrieves the values of the property matching the specified index name as a ResultPropertyValueCollection. The following snippet will demonstrate getting all returned properties and outputting the result to a console window:

DirectoryEntry rootEntry = new DirectoryEntry(); // Entire domain…

DireectorySearcher rootSearcher = new DirectorySearcher(rootEntry, “(sn=Hamilton)”);

SearchResult searchResults = rootSearcher.FindOne();

// Get the properties returned…

ResultPropertyCollection propertyCollection = searchResults.Properties;

// Output…

foreach (string thisProperty in propertyCollection.PropertyNames)

{

foreach (Object propertyValue in propertyCollection[thisProperty])

{

Console.WriteLine(thisProperty + “ = “ + propertyValue);

}

In the future I will introduce ADSI API and application code and we will see about developing a small application that will take some of what we have reviewed in these three parts and create a directory browser sample application.

I want to note that for the sample code so far, if you are not executing this on an actual AD domain controller, you will need to change the new DirectoryEntry() code to include the root, username and password of the context you are trying to connect as (we have reviewed this in previous lessons).

Finally, please forgive any typo’s – I try hard to make sure there are none.

I have received a great deal of feedback over the little I have posted so far, and I hope this posting is helpful for some. I apologize again for taking so long to get this series posted.

.Net Directory Services Programming - C# - Part 2 - DirectoryEntry Binding and AD Properties

Michael J. Hamilton, Sr. — Sat, 10 Nov 2007 14:43:45 GMT

.Net Directory Services Programming – C# - Part 2

Topics Covered

Binding – How to connect to directory services and the flexibility of the bind process.

Properties – Review of the most commonly used AD properties, and a look at a few others.

Binding

You will remember in Part 1 that we provided a very simple code example of binding to AD and retrieving the object reference for the user object CN=Mike Hamilton. Here I want to review a little more in detail the binding process.

Binding The Default Server

Often called serverless binding, or binding to your root context, the following shows the simplest of binding calls:

DirectoryEntry newEntry = new DirectoryEntry();

There is one major assumption here: You must be logged into the directory service (or the application you are executing must be) – otherwise the call will fail. This call will return the default server, or default root context – the server that validated your logging onto this network. I will review this in more detail shortly.

Passing The Directory (or ADsPath – we’ll review this in a later Part).

Here we pass the specific server and context that we want to bind to. Borrowing from Part 1 – you’ll remember how we bound to the specific user object.

DirectoryEntry userEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/CN=Mike Hamilton,DC=developer,DC=Hamilton,DC=com”);

Here we specify the context of the bind. Note, this can be any server within our domain or even another domain within our directory forest.

Passing The Path and Credentials to Bind

Here we want to bind to a specific path, and provide credentials that validate we have the permission to do so. This is important as you delve into security in later Parts.

DirectoryEntry userEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/CN=Mike Hamilton,DC=developer,DC=Hamilton,DC=com”, “<adminAccountName>”,”<adminPassword”);

Here you would replace adminAccountName and adminPassword with the actual credentials you want to user. Those can be the administrator account or any account that actually has permissions to perform the binding.

Passing The Path, Credentials, and Authentication Type

Not only can we bind with specific credentials, but we can also specify the authentication type we wish the directory service to use. For example:

DirectoryEntry userEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/CN=Mike Hamilton,DC=developer,DC=Hamilton,DC=com”, “<adminAccountName>”,”<adminPassword”, AuthenticationTypes.Secure);

We will review the AuthenticationTypes when we review AuthenticationTypeEnum in our security review.

Passing a Native ADSI Object Reference

You will get more into this type of binding when you get into security. For now, I am presenting this for an example/reference for future reviews.

DirectoryEntry iAdsEntry = new DirectoryEntry(IADSObject);

As we move through the different presentations on this topic, we will touch on each of the bindings methods presented, offering examples / benefits of that method.

Properties in AD

I clarify here – AD (Active Directory). I should note that LDAP is LDAP across most directory providers. I emphasize AD here because some of the examples I will use are specific to AD insofar as the default behavior of a property or binding context. I will explain those when applicable, and will make a notation in the example conveying that it is an AD specific property or context.

As mentioned previously, AD (and most directory providers) has a hoard of properties that are available to the developer. Here I want to present some of the most common. What is important to note is the syntax to use when referencing a specific property. (You will remember from Part 1 that property names are spelled out using Camel-Case and single names are in lower-case only.)

When a user is initially created, that First Name, Last Name, Account Login Name – ever wondered what these were in AD? There are some givens when interacting with these properties – and I want to point those out first.

The Account Login Name is written to a few AD properties that cannot be modified via code. There are some things you can do with an AD user object, but one of the most frustrating is renaming or copying to another directory. You can move an object, and of course, delete one – but let’s move forward.

When the account is first created, the following properties are assigned the names you provide when creating the account (and this is assuming you created the account with a management tool / snap-in that facilitates user management – like AD Users & Computers (dsa.msc)):

First Name = givenName
Last Name = sn
Login Account Name = sAMAccountName, name, dn

If you wanted to retrieve these values using LDAP, and following our example in Part 1, we would do something like the following:

using System;

using System.DirectoryServices;

namespace DirectoryUtility

public class Main()

{

DirectoryEntry userEntry = new DirectoryEntry(“LDAP://developer.hamilton.com/CN=Mike Hamilton,OU=Developers,OU=Accounts,DC=developer,DC=hamilton,DC=com”);

string loginID = userEntry.Properties[“sAMAccountName”].Value.ToString();

string firstName = userEntry.Properties[“givenName”].Value.ToString();

string lastName = userEntry.Properties[“sn”].Value.ToString();

MessageBox.Show(“Login ID: “+loginID.ToString()+”\r\n Full Name: “+firstName.ToString()+” “+lastName.ToString(),”Results”);

}

Yes, this is a rough example, and it does not allow for exception handling. The objective was to show you how to reference just these fields.

Here I’ll list a few (I say a few lightly – there are dozens) properties that you will commonly use or need to use:

sAMAccountName – user ID of the account created (Note, when programmatically creating/adding users – you have control over this field – but not after the object has been added).
name – same value as the sAMAccountName property.
givenName – First Name of the user.
sn – or Sur Name – Last Name of the User
displayName – typically, the same as the name, and sAMAccountName
userPrincipalName – the same as name, sAMAccountName
co – Country
mail – single email address value (I’ll demonstrate how we can maintain multiple emails in another Part).
telephoneNumber – User’s phone number
description – A description of this account
userAccountControl – The enumerated property that we’ll use to manage the user’s account – access, password change, locked, and others.
wWWHomePage – User’s default homepage –optional.
parent – Parent owner object. For example, the name of the OU the user account is in.
cn – Cononical – or Common Name – usually the combination of givenName + sn (NOTE: If you have migrated from another system, like NT4 to AD 2000 – this value is the same as the name, sAMAccountName, and displayName – by default, and it cannot be changed)

How to list and view all properties available with LDAP?

The following code snippet shows how to step through the properties associated with a DirectoryEntry object. (NOTE: This code assumes there is a listbox named propertiesListBox on a form that we can add the properties to.)

private void PopulateProperties(DirectoryEntry userEntry)

{

if (userEntry!=null)

{

propertiesListBox.Clear();

foreach (string propertyName in userEntry.Properties.PropertyNames)

propertiesListBox.Items.Add(propertyName);

}}

SUMMARY

I realize that a lot of this is not meat and potatoes yet, but those Parts are coming. I wanted to take the time to introduce some fundamentals because I realize there are a lot of developers out there that have not been introduced to DirectoryServices, and there is a lot to learn!

In our next couple of Parts we are going to look at the DirectorySearcher, the other major class in the DirectoryServices namespace, and then we’re going to look at a few basic examples of user / object management. We will start our own solution that will end up in a complete application that will allow you to connect to a directory service, list accounts and objects in that service, add accounts, add groups, and add other specific objects.