Getting and Setting Properties

The most common uses for ADSI objects are reading data from them and changing data for them. This object data is found in the object properties.

Getting Properties Values

All ADSI objects, with the exception of the Namespaces object, implement the COM interface IADs, which has six properties. For more information, see ADS Namespaces Container.

The IADs interface supports the following methods.

The following code example displays the standard IADs properties for a specific computer in a specific domain.

Private Sub DisplayIADsInfo(strDomain As String, strComputer As String)
	Dim oComputer As IADs

	On Error GoTo Cleanup
	Set oComputer = GetObject("WinNT://" & strDomain & "/" & strComputer & ",computer")

	Debug.Print "Name is " & oComputer.Name
	Debug.Print "Class is " & oComputer.Class
	Debug.Print "GUID is " & oComputer.Guid
	Debug.Print "ADsPath is " & oComputer.ADsPath
	Debug.Print "Parent is " & oComputer.Parent
	Debug.Print "Schema is " & oComputer.Schema

Cleanup:
	oComputer = Nothing
End Sub

The following code example produces output similar to the following.

Name is MYMACHINE
Class is Computer
GUID is {DA438DC0-1E71-11CF-B1F3-02608C9E7553}
ADsPath is WinNT://mydomain/MYMACHINE
Parent is WinNT://mydomain
Schema is WinNT://mydomain/Schema/Computer

The basic ADSI properties can be used to identify an object and where it is located in the directory hierarchy, but the most useful object data is stored in other properties that are specific to that object's class.

The following code example returns the full name of a user when given the username.

Private Sub DisplayUserFullName(strDomain As String, strUserName As String)
	Dim oUser As IADs

	On Error GoTo Cleanup

	Set oUser = GetObject("WinNT://" & strDomain & "/" & strUserName & ",user")

	Debug.Print "The full name for " & strUserName & " is " & oUser.FullName

Cleanup:
	oUser = Nothing
End Sub

The following code example produces output similar to the following when given the username "adsitest".

The full name for jeffsmith is Jeff Smith.

There is also an alternate syntax for retrieving property values. All ADSI objects implement the IADs::Get method, which may be used instead of the dot operator to read a given property.

The following code example produces the same result as the previous example.

Private Sub DisplayUserFullName(strDomain As String, strUserName As String)
	Dim oUser As IADs
	Dim strFullName As String

	On Error GoTo Cleanup

	Set oUser = GetObject("WinNT://" & strDomain & "/" & strUserName & ",user")

	strFullName = oUser.Get("FullName")

	Debug.Print "The full name for " & strUserName & " is " & strFullName

Cleanup:
	oUser = Nothing
End Sub

Refreshing the Local Cache

To avoid making unnecessary and slow network calls, ADSI caches properties locally. When an object is first bound to, the local property cache is empty. The first time that a property is retrieved, ADSI retrieves all the property values for that object and places them in the local cache. All further retrieval of properties will retrieve the values from the local cache. The IADs::GetInfo method explicitly updates the local cache from the underlying directory service. For more information about the ADSI property caching mechanism, see The ADSI Property Cache.

Setting Property Values

Setting a property value is similar to retrieving a property value, but the syntax is reversed.

The following code example sets the value of the FullName property for an object using the dot notation.

oObject.FullName = "Account for testing ADSI"

Setting property values can also be accomplished by calling the IADs::Put method. The Put method takes the name of the property that should be set and the new property value. The following code example produces the same effect as the last example.

The following code example sets the value of the FullName property for an object using the IADs::Put method.

oObject.Put "FullName", "Account for testing ADSI"

Setting a property value only changes the value in the local cache. The IADs::SetInfo method is used to write the changed values to the underlying directory service. For more information about the ADSI property caching mechanism, see The ADSI Property Cache.

oObject.FullName = "Account for testing ADSI"
oObject.SetInfo

Caution  Call SetInfo when changes are made to properties of an ADSI object; otherwise, those changes are only applied to the local cache, and not to the underlying directory service. Failing to call SetInfo will result in the loss of new data.

The GetInfo method overwrites all property values in the cache, if the GetInfo method is called after making changes to the properties, but before SetInfo is called, the changes are lost.

The following code example shows how to implement SetInfo and GetInfo.

Dim oUser As IADs

' Bind to a specific user object.
Set oUser = GetObject("LDAP://CN=Jeff Smith,CN=Users,DC=fabrikam,DC=com")
 
' Code assumes that the property description has a single value in the directory.
' Be aware that this will IMPLICITLY call GetInfo because at this point GetInfo
' has not yet been called, implicitly or explicitly, on the user object.
Debug.Print "User's title is " + oUser.Get("title")

' Change the property value in the local cache.
oUser.Put "title", "Vice President"
Debug.Print "User's title is " + oUser.Get("title")

' Call GetInfo, which overwrites the updated value because SetInfo has not 
' been called.
oUser.GetInfo
Debug.Print "User's title is " + oUser.Get("title")

' Change the property value in the local cache.
oUser.Put "title", "Vice President"
Debug.Print "User's title is " + oUser.Get("title")

' Call SetInfo, which will write the properties to the underlying directory 
' service.
oUser.SetInfo
Debug.Print "User's title is " + oUser.Get("title")

Assuming that the previous value of the title attribute is "Tester", the results of running the previous code example are as follows.

User's title is Tester
User's title is Vice President
User's title is Tester
User's title is Vice President
User's title is Vice President