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.
back to the top
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:
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
back to the top