HOW TO: Use ADSI to Set LDAP Directory Attributes

Article translations Article translations
Article ID: 260251 - View products that this article applies to.
This article was previously published under Q260251
Expand all | Collapse all

On This Page

SUMMARY

This step-by-step article describes how to use Active Directory Services Interface (ADSI) to create, change, and remove Lightweight Directory Access Protocol (LDAP) directory attribute values.

Use ADSI to Set LDAP Directory Attributes

ADSI is Microsoft's COM implementation for generic directory access. The ADSI LDAP provider implements the LDAP version 3.0 specification, as defined in Request For Comments (RFC) 2251.

Within commonly used directories that support LDAP, an attribute without a value does not exist. When the attribute value is set to a non-null value by a change, replace, or append operation, the attribute is created if it does not already exist.

Similarly, if an attribute is modified to have no value (or values), the entire attribute is removed. At times you may want to set an attribute to null. While this concept does not exist in directories that support LDAP, you can accomplish this by removing the attribute entirely and specifying that the property is to be cleared.

This behavior is consistent with the LDAP specification. Queries of the attribute value must expect the absence of the attribute itself and handle any error that may arise.

An update operation replaces all existing values of the given attribute with the new values listed, creating the attribute if it does not already exist. A replace operation with no value deletes the entire attribute if it exists, and is ignored if the attribute does not exist.

An append operation adds values to attributes that can have multiple values, and creates the attribute if it does not already exist.

A delete operation removes the listed values from the given attribute, removing the entire attribute if all current values of the attribute are listed for deletion.

A clear operation removes all values from the attribute and removes the attribute itself from the parent object.

Two ADSI methods, Put and PutEx, are provided for setting attribute values.

You can use the Put method for simple attribute assignment, but not to remove an attribute. Attempts to use the Put method to set the attribute value to null or an empty string (for instance) cause an error. You can use the Put method to set the value of an attribute that can have multiple values, but it replaces any existing values. The syntax for the Put method is as follows:
  <Object>.Put <attribute name>, <value>

-or-

  <Object>.<property> = <value>
The PutEx method is more comprehensive, and can be used to assign attribute values, to add or remove values from attributes that can have multiple values, and to clear the value of an attribute. As described above, clearing the attribute has the effect of removing the attribute from the directory structure. The syntax for the PutEx method is as follows:
  <Object>.PutEx <controlcode>, <attribute name>, <value(s)>
Values for ControlCode are as follows:
Const ADS_PROPERTY_CLEAR = 1
Const ADS_PROPERTY_UPDATE = 2
Const ADS_PROPERTY_APPEND = 3
Const ADS_PROPERTY_DELETE = 4
					
When changing an attribute value, if the attribute can only have a single value, you can use the Put method. The Put method overwrites any existing values. If the attribute can have multiple values and additional values are to be added, use the PutEx method and place the additional values into an array.

NOTE: After using the Put or PutEx method to modify object attribute values, you must explicitly call the SetInfo method to save the changes:
  <Object>.SetInfo
The following examples create, change, and clear the values of an attribute value called "myAttrib" of an object "myObject":
'Using Put with a single value.
myObject.Put "myAttrib", 1  'overwrites any existing value

'The simplest form, works only if the attribute name is a single word.
myObject.myAttrib = 1

'Using Put for multi-value attribute.
Dim arrayValues(1)
arrayValues(0) = CStr(1)
arrayValues(1) = CStr(2)
myObject.Put "myAttrib", arrayValues

'Using PutEx for single-value attribute.
myObject.PutEx ADS_PROPERTY_UPDATE, "myAttrib", 0 

'Using PutEx to set multi-value attribute.
Dim arrayValues(1)
arrayValues(0) = CStr(1)
arrayValues(1) = CStr(2)
myObject.PutEx ADS_PROPERTY_UPDATE, "myAttrib", arrayValues 

'Using PutEx to append addition values to multi-value attribute.
arrayValues(0) = CStr(3)
arrayValues(1) = CStr(4)
myObject.PutEx ADS_PROPERTY_APPEND, "myAttrib", arrayValues 

'Clearing (or removing) an attribute.
myObject.PutEx ADS_PROPERTY_CLEAR, "myattrib", 0 

'Explicitly save all changes.
myObject.SetInfo
				

REFERENCES

For additional information on ADSI, see the following Microsoft Web site:
http://msdn2.microsoft.com/library/aa772170.aspx
For additional information on LDAP, click the article numbers below to view the articles in the Microsoft Knowledge Base:
196455 Introduction to Lightweight Directory Access Protocol (LDAP)
221606 Common LDAP RFCs

Properties

Article ID: 260251 - Last Review: September 28, 2007 - Revision: 3.3
APPLIES TO
  • Microsoft Active Directory Service Interfaces 2.5, when used with:
    • the operating system: Microsoft Windows 2000
Keywords: 
kbhowtomaster kbmsg KB260251

Give Feedback

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com