Native Directory Services Programming Landscape

Windows includes a variety of APIs for working with directory services in native or "unmanaged" code. Since all of the .NET APIs we'll be discussing in this book build on these native APIs, it is helpful to know a little bit about them as well.

Native LDAP

wldap32.dll is a DLL included with Windows that contains Microsoft's implementation of the standard LDAP API defined in the RFCs we mentioned in Chapter 1. It works directly on the TCP/IP protocol and is designed to be used from C and C++. This native LDAP implementation is the lowest-level API included with Windows for working with LDAP directories. It is not designed to be accessed via COM automation clients such as VBScript, JScript, and Visual Basic. The new SDS.P namespace is actually using this library for a lot of its functionality via P/Invoke.

The Net* APIs

Microsoft has a set of APIs in the Windows Platform SDK that are designed to provide access to the Windows Security Account Manager (SAM) infrastructure. All of these APIs are prefixed with the word "Net," so we refer to them as the Net* APIs. These APIs were originally designed to work with the Windows NT4 domain controller model and local machine accounts, but they also have limited support in Active Directory for backward compatibility. They communicate with remote machines via the Windows remote procedure call (RPC) infrastructure.

The Ds* Active Directory APIs

When Microsoft introduced Active Directory with Windows 2000, it included with the Windows Platform SDK a set of APIs for performing tasks specific to Active Directory. All of these APIs are prefixed with the letters "Ds" (e.g., DsGetDCName), so we refer to them collectively as the Ds* APIs. Even though the primary interface for managing Active Directory is LDAP, a variety of functions, such as locating an appropriate domain controller and managing replication, cannot be accomplished via LDAP alone. These APIs fill that gap. As with all APIs in the standard platform SDK, these are designed to be accessed via C and C++. They also communicate with Active Directory through the Windows RPC infrastructure.

Active Directory Service Interfaces (ADSI)

Active Directory Service Interfaces (ADSI) is a COM-based native API included with all versions of Windows for accessing a variety of different directory services using a provider model. Different ADSI providers implement the ADSI COM interfaces and provide access to specific directory service protocols via these standard interfaces. For example, the LDAP ADSI provider allows access to LDAP services and the WinNT provider allows access to the SAM system. Windows ships with a variety of different ADSI providers, including the two we already mentioned. The ADSI provider model is open, so third parties may also implement their own providers for their directories.

Unlike the other APIs we have been discussing, ADSI is higher level and designed primarily for use from automation clients such as VBScript and JScript, as well as from (non-.NET) Visual Basic and C++. As a result, ADSI is significantly easier to use than the other APIs and opens up the world of directory services programming to the scripting community. The ease with which developers and administrators can use and create scripts to maintain all of Microsoft's directory services has been crucial to its successful adoption.

As with any higher-level abstraction, ADSI generally performs more slowly than the APIs it encapsulates as we get further from the metal, so to speak. This is the price we pay for abstraction. However, because all of these APIs tend to access network resources, the network itself is often the limiting factor in performance. When used thoughtfully, ADSI can offer extremely good performance that would be more than acceptable in most situations.

It is probably fair to say that the LDAP provider for ADSI is the most full featured of the ADSI providers and fits in with the ADSI interface model the best. For example, the ADSI search interface, IDirectorySearch, is fully exploited only by the LDAP provider.[1] As with any API that tries to provide a "one size fits all" interface to a variety of different systems, there are definitely some rough edges and missing features with all of the ADSI providers. For our purposes, ADSI (and its managed counterpart, System.DirectoryServices) represents the sweet spot for most of the work we want to do. The remaining rough spots and subtleties are what a lot of the rest of this book is about.

[1] IDirectorySearch also works with the NDS provider, but it is rarely used and we do not cover it in this book.

Figure 2.1 shows the familiar architectural "layer" model for the entire API stack.

Figure 2.1. Directory Services Programming Landscape