Visual CSharp .NET Developer's Handbook (2002) [eng]

•microsoft.public.platformsdk.active.directory

•microsoft.public.win2000.active_directory

Understanding the Active Directory Service Interface (ADSI)

Active Directory provides many features that make it easier to manage large networks and safeguard the information they contain. While the MMC snap-ins that Microsoft provides as part of Windows 2000 perform adequately for standard classes that come with Active Directory, customized classes may require more in the way of management capability. Consequently, it's important that Active Directory also comes with a set of services that you can access through an application program. ADSI helps you to interact with Active Directory using a single set of well-defined interfaces.

Microsoft designed ADSI to be easy and flexible to use. ADSI provides few interfaces and they're all relatively easy to understand, which means your learning curve won't be as steep as for other products currently on the market. Two completely different groups use ADSI as a means for automating directory services tasks. Network administrators fall into the first group. Because ADSI relies on COM, a network administrator could access the features that it provides with relative ease from a scripting language. Obviously, developers fall into the other group. Microsoft is hoping that developers will create Active Directory–enabled applications using the lower-level ADSI features.

Tip Active Directory has garnered a lot of interest from non-Microsoft sources that can help you decipher what Active Directory can mean for your organization. One of the better places to look for information about the Active Directory Server Interface (ADSI) is the 15 Seconds website at: http://www.15seconds.com/ focus/ADSI.htm. This site contains articles, links to other sites, a few examples, and a list of Microsoft Knowledge Base articles for ADSI-specific topics. If you want to learn about Microsoft's view of ADSI, then check out the Active Directory Services Interfaces Overview site at http://www.microsoft.com/windows2000/ techinfo/howitworks/activedirectory/adsilinks.asp.

Now that I've introduced you to ADSI, let's take a more detailed look. The following sections will help you understand what ADSI can provide in the way of programming support. We'll look at the actual mechanics of using ADSI later in the chapter.

Working with a Common API

ADSI has some advantages besides working with Active Directory, if you take the Microsoft approach to performing tasks. Most organizations have more than one directory service structure in place. The three most common directory services are those used by the network, the e-mail program, and groupware. If all of the directory service products in your organization conform to either the LDAP or NSPI standards, then you can use ADSI to manage them all. Of course, ADSI won't work in some situations, because the product vendor didn't know about ADSI during development and didn't provide the required interface elements.

Note ADSI actually contains two levels of API support. The first level provides support for Active Directory structures that can support automation. The COM components that provide access to these structures are accessible from just about any language, as long as

the language supports automation. This includes support for Java, Visual Basic, VBScript, JavaScript, and ASP. Administrators also obtain this level of support through a standard MMC snap-in. The second level of support is for structures that can't support automation. To gain access to this second level of support, you must use a programming language like Visual C++.

So, how does Microsoft hope to get these third-party directory services to work with ADSI? Most of the core logic depends on LDAP or NSPI, which are common standards for directory access. All a third-party vendor really needs to do is write an ADSI provider that allows directory services access through the components that Microsoft provides. That's why access to any directory service is theoretical at this point—Microsoft has to convince third parties to supply the required provider so you can gain access to these other directory services using one interface.

If Microsoft does successfully write ADSI providers themselves, or convince third-party vendors to perform the task, then you'll gain an important benefit. Any application designed to work with ADSI will also work with any directory service. In short, you could write a single application that would allow you to manage groupware, e-mail, and the network. What this means for developers is that you'll no longer waste time writing the same application multiple times because the directory services API for each product that your company uses is different.

Creating New Objects

Like Active Directory, you aren't limited to the objects that Microsoft provides for ADSI. You can write new objects that extend the tasks that ADSI can perform. In some respects, this means you can write your own customized programming platform. Of course, accessing the directory database won't be a problem because ADSI supports OLE-DB.

ADSI also divides the kinds of objects that you can create into two categories. Container objects can act as objects. However, in most cases, they hold other objects and help you interact with those objects in a consistent manner. Leaf objects are stand-alone components designed to perform a single task.

Working with Namespaces

Every object on a network has to have a unique identification. Depending on the directory service, this identification method might look similar to the method you use to access a file on your hard drive. However, most namespaces use the X.500 standard for naming, which consists of object type definitions, followed by the object type value. Here's an example.

CN=John;OU=Editorial;O=NewMagPub

In this example, John is the object that we want to work with. CN stands for the context name. John is located within an organizational unit known as Editorial, which is part of an organization called NewMagPub. As you can see, this method of accessing a particular object on the network is very easy to understand and use.

ADSI doesn't support every namespace, but it does support four of the most common namespaces: Active Directory services (ADs://), LDAP (LDAP://), Windows NT/2000 (WinNT://), and Novell Directory Services (NDS://). Notice that this namespace convention

looks like a URL. You'll find the namespace ends up looking like an URL because of the DNS support that Active Directory provides. In fact, this is one of the reasons that Microsoft makes it so easy to find the fully qualified DNS name for the resources on your network.

Note that you can access Active Directory entries using more than one namespace. Each namespace provides certain benefits when accessing information. We'll discuss the effect of using a particular namespace later in the chapter.

Working with the ADSI API

ADSI is the API that enables you to work with Active Directory and helps you to add the new features that Active Directory provides to your applications. Like many other parts of Windows Server, ADSI relies heavily on COM components. In fact, many of your applications will require direct access to these components, despite functionality provided by the .NET Framework. We'll see one such example in the sample code for this chapter.

Tip It's interesting to note that only Windows Server products come with Active Directory as part of the package. Microsoft does provide Active Directory support for Windows 9x, along with a setup for older versions of Windows NT. You can find links for all four levels of support at http://www.microsoft.com/NTServer/ nts/downloads/other/ADSI25/. This site also includes a link for the Active Directory Services Interfaces SDK. If you want full ADSI information, check the Active Directory Service Interfaces website at http://www.microsoft.com/windows2000/techinfo/ howitworks/activedirectory/adinterface.asp.

The most common ADSI API COM functionality appears in the ACTIVEDS.TLB file found in the Windows System32 folder. To add this type library to your project, right-click the References folder in Solution Explorer, and then choose Add Reference from the context menu. You'll see an Add Reference dialog box similar to the one shown in Figure 8.2. Notice that the figure shows the ACTIVEDS.TLB entry highlighted.

Figure 8.2: You'll need to add COM support for Active Directory to many of your projects.

When working with COM, you need to understand the interfaces it provides. One way to see the features that the ACTIVEDS.TLB file provides is to look at them in Object Browser.

every Active Directory interface, so you'll need to resort to COM to gain access to these interfaces. We'll discuss both problems in the sample applications.

The DirectoryServices namespace includes class counterparts for the interfaces we've discussed so far (and will continue to discuss as the chapter progresses). The main focus of the classes provided in the System.DirectoryService namespace is implementation of the IADsOpenDSObject interface. Once you have an open connection to Active Directory, you can begin to manipulate the data it contains. The following list contains a description of the major classes found in the System.DirectoryService namespace.

DirectoryEntries Provides access to the child entries for an Active Directory entry. Essential tasks include adding, removing, and finding the child entries. You'll use the DirectoryEntry class to modify the child entries.

DirectoryEntry Provides access to a single Active Directory entry, including the root object. You can also use this class to access some of the information found in schema entries. Essential tasks include name and path modification, identification of children and parent, property modification, and obtaining the native object. When working with the native object, you must cast it to an IADs COM object. C# also has access to a Directory-Entry control that makes using this class easier. You'll learn how to use this control in the example application.

DirectorySearcher Enables you to search Active Directory for specific entries. You can search for one or all matching entries, cache the entries locally, filter and sort the search results, and set the search environment. For example, you can set timeouts for both client and server. C# also provides a control version of this particular class that makes configuration easier.

DirectoryServicesPermission Sets the code access permissions (security) for Active Directory. The Assert() method enables to you validate that the calling code can access the requested resource. You can also copy, deny, and demand permissions, as well as perform other tasks.

DirectoryServicesPermissionAttribute Permits a declarative System.DirectoryServices permission check. You can either match a permission to a specific permission, or create a new permission.

DirectoryServicesPermissionEntry Sets the smallest unit of code access security permission provided by System.DirectoryServices.

DirectoryServicesPermissionEntryCollection Creates a strongly typed collection of DirectoryServicesPermissionEntry objects. You can perform all of the usual collection tasks, including counting the number of items and working with a specific item. Other methods enable you to add, remove, insert, or copy permissions.

PropertyCollection Enables you to examine the properties for a single DirectoryEntry object. You can count the number of properties, obtain a list of property values, obtain a list of property names, or extract the value of a single property.

PropertyValueCollection Enables you to examine the property values for a single DirectoryEntry object. You can count the number of values, set a specific property value, or set the values for the entire collection. Methods help you perform all of the usual collection

tasks, including counting the number of items and working with a specific item. Other methods enable you to add, remove, insert, or copy permissions.

ResultPropertyCollection Enables you to examine the properties for a SearchResult object. You can count the number of properties, obtain a list of property values, obtain a list of property names, or extract the value of a single property.

ResultPropertyValueCollection Enables you to examine the property values for a SearchResult object. You can count the number of items in the collection and work with specific items. Methods enable you to perform specific tasks such as to copy the collection to an array or determine if the collection contains a specific property.

SchemaNameCollection Contains a list of schema names that you can use with the SchemaFilter property of the DirectoryEntry object. You can count the number of items in the collection and work with specific items. Methods help you perform all of the usual collection tasks, including counting the number of items and working with a specific item. Other methods enable you to add, remove, insert, or copy permissions.

SearchResult Contains the results of using a DirectorySearcher object to look for specific Active Directory entries. The SearchResult object contains an entire Active Directory node, beginning with the location of the first object found.

SearchResultCollection Contains a collection of SearchResult objects. You can obtain a count of the SearchResult objects, obtain a handle to the IDirectorySearch::ExecuteSearch interface, work with a specific item, or obtain a list of properties used for the search. Methods enable you to perform specific tasks such as to copy the collection to an array or determine if the collection contains a specific SearchResult object.

SortOption Determines how Windows XP sorts the results of a search. You can specify both the search direction and search property.

As you can see, you can perform most tasks using managed code. In the few cases where you need to perform a task using the COM interfaces, you can obtain a copy of the object using built-in method calls (see DirectoryEntry for an example). Of course, several issues remain besides ease of access. One of the most important issues is thread safety—an important consideration in a distributed application. Generally, you'll find that public static class members are thread safe while instance members aren't. This limitation means you must use class members carefully and take steps to ensure that method calls occur in a thread-safe manner.

Working with the Active Directory

Active Directory is a complex part of Windows Server. You must consider database elements, interaction with other directory services, management issues, and even a new set of programming features implemented by the COM components that make up ADSI. This section discusses the programming considerations for Active Directory.

The fact that we're managing a large distributed database changes the entire picture for the programmer. You need to consider programming requirements that other kinds of applications don't even touch. For example, how do you create a connection to an object that may reside in