ADSI Object Library Architecture

The ADSI object library is a very approachable object library. Although it does not contain many objects, you can perform many functions with the objects in the library. The only potential difficulty in using the ADSI object library is understanding how to access the objects in your applications using distinguished pathnames. At first, these pathnames can be a little intimidating, but after you experiment with ADSI and its objects, you will understand how to exploit the power of these paths. We'll discuss creating paths later in this chapter in the section titled "Creating Paths to Active Directory Objects and Attributes."

In the ADSI architecture, every element in a directory service, such as the Exchange Server configuration information, is represented by an ADSI object. The interfaces supported by the ADSI object are determined by the underlying functionality of the directory object. For example, a mailbox in Exchange Server, which does not contain directory objects under it, supports the IADs interface. In contrast, a container in Active Directory, which can hold objects such as mailboxes, distribution lists, and other containers under it, implements the IADsContainer interface. Because the requirements for a directory object that contains other directory objects extend beyond those for a single directory object, ADSI provides more methods and properties, through extra interfaces, for them.

IADs and IADsContainer Interfaces

The primary interfaces you will use when working with ADSI objects are the IADs interface and the IADsContainer interface. The IADs interface is required for all ADSI objects. It provides properties that describe the object ”in essence, the metadata of the object ”and methods that allow you to manage the actual directory information that the object contains. ADSI stores this directory information in a property cache, which gives you a mechanism to batch changes or additions to a specific object in a temporary location and then burst this information to the directory service in one call. This property cache is useful because some programming languages, such as Visual Basic, do not provide native batching mechanisms, and without a property cache, every change you make to an ADSI object is put over the wire, decreasing the performance of your application.

The property cache is useful, but only if you remember to use it! The most common mistake new ADSI developers make is not calling the specific ADSI method SetInfo to flush the cache and submit object modifications to the directory. If you exit your application and do not call this method then the changes you make will not be persisted in the directory. The second most common mistake new ADSI developers make is not calling the GetInfo method to refresh the cache after making changes. The SetInfo method does not automatically refresh the cache for you.

In addition to supporting the GetInfo and SetInfo methods, the IADs interface supports the Get , GetEx , GetInfoEx , Put , and PutEx methods. Get and Put do exactly what their names imply: Get retrieves a specific property from the directory, and Put saves the value for a specific property in the property cache. The versions of these methods with the Ex suffix allow you to get or put a multivalue property. A multivalue property can contain multiple values of the same type. The best example of a multivalue property in Active Directory is the reports property. Because one person can have many direct reports, the reports property in the directory is a multivalue property ”multiple direct report names can be stored in a single property for the directory object named reports. To access this property from ADSI, you must use the GetEx method. GetInfoEx is provided so that you can specify which properties to refresh in the property cache and avoid having to reload the entire cache from the underlying directory service.

The properties that the IADs interface implements are Name , AdsPath, GUID , Class , Schema , and Parent . (For our purposes, the Schema and Parent properties are not as important as the other four, so this discussion will focus on Name , AdsPath , GUID , and Class .) The Name property returns the relative name of the object. The AdsPath property returns the path to the object. In Exchange Server, this is the LDAP query string that is used to access the object. The GUID property returns the GUID of the object from the underlying directory. The Class property is important because it returns the schema class name of the object. This property and its return value will get a bit more attention in the next section.

IADsContainer Interface

As mentioned earlier, if a directory object contains other objects, the directory object is considered a container. In ADSI, a container implements not only the IADs interface but also the IADsContainer interface. The IADsContainer interface provides methods to traverse the child objects in the container as well as modify the container's properties. As you will see in the sample applications in this chapter, you can use the For Each construct in Visual Basic or VBScript to easily loop through all the child objects below a container object and retrieve individual properties from each child object. By traversing the individual objects under the container, you can easily build a hierarchical view of the information stored in Active Directory.

Other ADSI Interfaces

Covering the other ADSI interfaces is beyond the scope of this book, but you should know that ADSI provides a powerful feature set so you can build not only directory applications that work with Exchange Server but also applications that work with other directory services. For example, ADSI defines an IADsComputer interface that lets you store information about a computer in a directory service. ADSI also defines interfaces such as IADsPrintQueue and IADsPrintJob , which enable you to list printers available in the directory service and store specifics about the actual print jobs taking place on those print queues. For guidance on finding more information on the other types of ADSI interfaces, refer to the "Getting Help with ADSI" section later in this chapter.

Exchange Server Object Classes

You should be aware of some important classes in Exchange Server when you develop your applications:

• container    Identifies the object as a container for other objects in the directory.

• group    Corresponds to distribution lists in the Exchange Server directory.

• person    An abstract class that represents any object that can receive mail so other objects, such as distribution lists, can inherit some attributes from the class. Because the person class is an abstract class, you can never create an explicit object from it.

• organizationalPerson    Represents recipients in the directory.

• contact    Corresponds to a custom recipient in the directory.