.NET Programming with System.DirectoryServices.ActiveDirectory (SDS.AD)

I am so pleased to announce a new white paper on MSDN by Ethan Wilansky that provides an introduction to the .NET 2.0 System.DirectoryServices.ActiveDirectory (SDS.AD) namespace. With the advent SDS.AD and System.DirectoryServices.Protocols (SDS.P) in .NET 2.0, directory services programming for the managed code programmer has come of age. These rich programming APIs bring to the .NET platform the ability to manage a directory that previously was only available through Active Directory Services Interface (ADSI) scripting, C++ or the LDAP API. If by chance you have not yet read the book A .NET Developer’s Guide to Directory Services Programming by Joe Kaplan and Ryan Dunn, I highly recommend it to you. It definitively covers System.DirectoryServices (SDS) and programming using the DirectoryEntry and DirectorySearcher object model. Although Joe and Ryan touch on SDS.AD and SDS.P at various points in the book, their focus primarily was on SDS. Therefore, Ethan’s papers are an excellent complement to their book.

By way of introduction, one of the design principles for the Directory Services namespaces was to introduce a low barrier to entry and self documenting object model. The intent is that programmers can learn the APIs quickly due to their strong typing, easy navigation between types, sensible defaults, simple initialization, convenient overloads and simple and straightforward entry points. The design goals were to solve specialized problems by simplifying the process of common directory services tasks, such as: topology management, schema management, replication management and trust management.

This paper of Ethan’s focuses on SDS.AD, SDS.P is in publishing now and I'll anounce it as soon as it comes available on MSDN. As mentioned, the SDS.AD namespace’s object model is built around Active Directory service tasks and includes such concepts as forest, domain, site, subnet, partition and schema. Ethan’s paper provides both a description and practical guidance on how to begin programming with SDS. AD for some common scenarios. A code sample accompanies the paper and can be downloaded here. Once you download and unzip the file, open the DirectoryServices.ActiveDirectory solution in VS 2005. If you intend to exercise all the functionality for Active Directory you will need to create a test environment, possibly in a VPC. To execute the Console against an ADAM instance (see my blog, Step 1: Get ADAM installed) you will need to open the ADAMData class, find localhost and change it to the full machine name of the computer the ADAM instance is located on and the port of that instance. For example:       
 Change This Line of Code From:
      static string adamConnectionString = "localhost:50000"; 
 To:
      static string adamConnectionString = "your_machine_name:your_port_number";

Now, build the console application, start a Command Prompt, cd to the bin directory and run DS.AD. Executed without any parameters the application will give you a list of its available commands. This coupled with the white paper should give you a great start with SDS.AD. Following are the scenarios exposed in the sample code:  Enjoy!

• Forest, domain, and ADAM reporting tasks
GetDomainData
GetForestData
GetGcData
GetDcData
GetSchemaData
GetSchemaClassData className
GetSchemaPropertyData propertyName
GetAdamPartitions

• Schema reporting and management tasks
GetAdamSchemaData
GetAdamSchemaClassData
GetAdamSchemaPropertyData
AddSchemaClasstoAdam
AddSchemaAttributetoAdam

• Topology reporting and management tasks
GetTopologyData forestName
CreateAdSite newSiteName
CreateAdamSite targetName newSiteName
CreateSubnet newSubnet siteName
CreateSiteLink siteName newLinkName
AddSiteToSiteLink siteName siteLinkName
RemoveSiteFromSiteLink siteName siteLinkName
MoveDcToSite sourceDC targetSite
DeleteAdSite siteName
DeleteAdamSite targetName siteName
DeleteLink linkName

• Replication reporting and management tasks
GetReplicationStateData
ReplicateFromSource partitionDN sourceServer targetServer
ReplicateFromNeighbors targetServer partitionDN
SyncAllServers partitionDN
CreateNewConnection sourceServer targetServer connectionName
SetReplicationConnection server connectionName
DeleteReplicationConnection server connectionName

• Trust reporting and management tasks
GetCurrentForestTrusts
GetCurrentDomainTrusts
GetTrustWithTargetForest
GetTrustWithTargetDomain
CreateCrossForestTrust targetForest userNameTargetForest password
SetForestTrustAttributes targetForestName
ChangeForestTrustToOutbound targetForestName userNameTargetForest password
AddExcludedDomain targetForestName targetDomainName
DisableDomainNetbiosName targetForestName targetDomainName
RepairTrust targetForestName userNameTargetForest password
RemoveForestTrust targetForestName userNameTargetForest password
RemoveDomainTrust targetDomainName userNameTargetDomain password