The Property Cache

You might expect that each time your application retrieves a property of an object, ADSI makes a request of the Active Directory server for the information. In reality this would be horribly inefficient, particularly over potentially slow network connections.

To minimize trips to the server and back, ADSI maintains a client-side property cache to hold an object's property values locally. Each entry in the cache contains information about the property's name, its data type, and its value or values. When an application requests an ADSI property or calls the Get or GetEx methods, ADSI first checks the local property cache to see whether the property is present. If it isn't, ADSI makes a request of the Active Directory server to retrieve all the object's properties at once to populate the property cache. Subsequent requests for properties are completed very quickly because ADSI does not need to return to the server for more information. Figure 6-3 illustrates the workings of the property cache.

Figure 6-3 The ADSI property cache.

ADSI creates the property cache when you bind to an object but does not fill it with values until you actually request a property. The first time a property that is not already in the cache is accessed, all the attributes of that particular object are transferred from the server to the client's property cache.

The GetInfo Method

Your application can also force ADSI to load or refresh the property cache by using the GetInfo method of the IADs interface. Refreshing the cache retrieves the current properties from the server. If your application stays bound to an object for a long time, it's possible that another application will update the directory data. Active Directory does not automatically refresh the property cache when changes are made by another application.

The following code, from the GetInfo.bas sample on the companion CD, shows how to call GetInfo using Visual Basic.

 ` Bind to the object
Set objADs = GetObject(strADsPath)
 ` At this point, the property cache is empty
` Use GetInfo to explicitly load it
objADs.GetInfo
 ` Use the IADs Get method to retrieve the distinguishedName attribute
strDN = objADs.Get("distinguishedName") 

Operational attributes are not retrieved by the GetInfo method and must be explicitly retrieved using the GetInfoEx method. Operational attributes are usually administrative attributes that are implemented internally by Active Directory but that don't appear in the schema. For example, many of the attributes for the RootDSE object are operational attributes.

The GetInfoEx Method

If you're like me, you cringe at the thought of all the properties of an object being loaded at the same time. What happens if the object has a large number of properties? Or from a more practical point of view, why should the property cache be loaded with all the properties of an object when you're only interested in one or a few select properties?

The clever ADSI folks think the same way, and they provided an additional method, GetInfoEx, to give applications control over which properties are loaded into the property cache.

GetInfoEx accepts a variant array of strings that identifies which properties of the object should be retrieved from the directory and placed in the cache. GetInfoEx works exactly like GetInfo, but it's more selective. The following code, from the GetInfoEx.bas sample on the companion CD, shows how to use GetInfoEx using Visual Basic.

 ` Bind to the object
Set objADs = GetObject(strADsPath)

` Fill an array with the properties we want to access
varProperties = Array("objectCategory", "distinguishedName")

` Use GetInfoEx to explicitly load only the properties listed in the array
` The second parameter is reserved for future use and must be zero
objADs.GetInfoEx varProperties, 0

` Display the properties
Debug.Print objADs.Get("objectCategory")
Debug.Print objADs.Get("distinguishedName")

` This next property isn't in the cache, so GetInfo will be 
` implicitly called
Debug.Print objADs.Get("whenCreated")