Dsml

With the new .NET 2.0 namespace System.DirectoryServices.Protocols you can access the Active Directory through DSML (Directory Services Markup Language). DSML is a standard defined by the OASIS group (http://www.oasis-open.org) that allows you to access directory services through a Web service.

To make Active Directory available through DSML, you must either have Windows Server 2003 R2 or you have to install DSML Services for Windows. You can download DSML Services for Windows from the Microsoft Web site: http://www.microsoft.com/windowsserver2003/downloads/feature packs/default.mspx.

Figure 22-17 shows a configuration scenario with DSML. A system that offers DSML services accesses the Active Directory via LDAP. On the client system the DSML classes from the namespace System.DirectoryServices.Protocols are used to make SOAP requests to the DSML service.

Figure 22-17

Classes in System.DirectoryServices.Protocols

The following table shows the major classes in the System.DirectoryServices.Protocols namespace.

Class	Description
DirectoryConnection	DirectoryConnection is the base class of all the connection classes that can be used to define the connection to the directory service. The classes that derive from DirectoryConnection are Ldap Connection (for using the LDAP protocol), DsmlSoapConnection, and DsmlSoapHttpConnection. With the method SendRequest a message is sent to the directory service.
DirectoryRequest	A request that can be sent to the directory service is defined by a class that derives from the base class DirectoryRequest. Depending on the request type, classes such as SearchRequest, AddRequest, DeleteRequest, and ModifyRequest can be used to send a request.
DirectoryResponse	The result that is returned with a SendRequest is of a type that derives from the base class DirectoryResponse. Examples for derived classes are SearchResponse, AddResponse, Delete Response, and ModifyResponse.

Searching for Active Directory Objects with DSML

This section looks at an example of how a search for directory services objects can be performed. As you can see in the code that follows, first a DsmlSoapHttpConnection object is instantiated that defines the connection to the DSML service. The connection is defined with the class DsmlDirectoryIdentifier that contains an Uri object. Optionally, the user credentials can be set with the connection:

 Uri uri = new Uri("http://dsmlserver/dsml"); DsmlDirectoryIdentifier identifier = new DsmlDirectoryIdentifier(uri); NetworkCredential credentials = new NetworkCredential(); credentials.UserName = "cnagel"; credentials.Password = "password"; credentials.Domain = "explorer"; DsmlSoapHttpConnection dsmlConnection =  new DsmlSoapHttpConnection(identifier, credentials); 

After the connection is defined, the search request can be configured. The search request consists of the directory entry where the search should start, an LDAP search filter, and the definition of what property values should be returned from the search. Here the filter is set to (objectClass=user), so that all user objects are returned from the search. attributesToReturn is set to null, and you can read all attributes that have values. SearchScope is an enumeration in the namespace System.Directory Services.Protocols that is similar to the SearchScope enumeration in the namespace System. DirectoryServices to define how deep the search should go. Here the SearchScope is set to Fullto walk through the complete Active Directory tree.

The search filter can be defined with an LDAP string or by using an XML document contained in the XmlDocument class:

 string distinguishedName = null; string ldapFilter = "(objectClass=user)"; string[] attributesToReturn = null;// return all attributes SearchRequest searchRequest = new SearchRequest(distinguishedName,  ldapFilter, SearchScope.Full, attributesToReturn); 

After the search is defined with the SearchRequest object, the search is sent to the Web service by calling the method SendRequest. SendRequest is a method of the DsmlSoapHttpConnection class. SendRequest returns a SearchResponse object where the returned objects can be read.

Instead of invoking the synchronous SendRequest method, the DsmlSoapHttpConnection class also offers the asynchronous methods BeginSendRequest and EndSendRequest.

 SearchResponse searchResponse =  (SearchResponse)dsmlConnection.SendRequest(searchRequest); 

The returned Active Directory objects can be read within the SearchResponse. SearchResponse. Entries contains a collection of all entries that are wrapped with the type SearchResultEntry. The SearchResultEntry class has the Attributes property that contains all attributes. Each attribute can be read with help of the DirectoryAttribute class.

In the code example the distinguished name of each object is written to the console. Next, the attribute values for the organizational unit (ou) are accessed, and the name of the organizational unit is written to the console. After this, all values of the DirectoryAttribute objects are written to the console:

 Console.WriteLine("\r\nSearch matched " + searchResponse.Entries.Count +  " entries:"); foreach (SearchResultEntry entry in searchResponse.Entries) { Console.WriteLine(entry.DistinguishedName); // retrieve a specific attribute DirectoryAttribute attribute = entry.Attributes["ou"]; Console.WriteLine(attribute.Name + "=" + attribute[0]); // retrieve all attributes foreach (DirectoryAttribute attr in entry.Attributes.Values) { Console.Write(attr.Name + "="); // retrieve all values for the attribute // the type of the value can be one of string, byte[] or Uri foreach (object value in attr) { Console.Write(value + "  "); } } } 

Adding, modifying, and deleting objects can be done similarly to searching objects. Depending on the action you want to do, you can use the corresponding classes.