Article ID: 260251
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.
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>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>.<property> = <value>
<Object>.PutEx <controlcode>, <attribute name>, <value(s)>Values for ControlCode are as follows:
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.
Const ADS_PROPERTY_CLEAR = 1 Const ADS_PROPERTY_UPDATE = 2 Const ADS_PROPERTY_APPEND = 3 Const ADS_PROPERTY_DELETE = 4
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>.SetInfoThe following examples create, change, and clear the values of an attribute value called "myAttrib" of an object "myObject":
For additional information on ADSI, see the following Microsoft Web site:
http://msdn2.microsoft.com/library/aa772170.aspxFor additional information on LDAP, click the article numbers below to view the articles in the Microsoft Knowledge Base:
(http://support.microsoft.com/kb/196455/EN-US/ )Introduction to Lightweight Directory Access Protocol (LDAP)
(http://support.microsoft.com/kb/221606/EN-US/ )Common LDAP RFCs
Article ID: 260251 - Last Review: June 19, 2014 - Revision: 4.0