Getting and Setting Properties

Now that you know how to bind to objects, it is time to do something useful with them. The most common things to do with objects are reading information from them and changing information about them. Both of these are accomplished through properties.

Getting Property Values

All ADSI objects, except for the Namespaces object (see ADS Namespaces Container), implement the COM interface IADs, which has six properties.

The IADs interface also supports the following methods.

The following script will display the standard IADs properties for a specific computer:

Dim myObj

Set myObj = GetObject("WinNT://MyDomain/mymachine,computer")
WScript.Echo "Name is " & myObj.Name
WScript.Echo "Class is " & myObj.Class
WScript.Echo "GUID is " & myObj.GUID
WScript.Echo "ADsPath is " & myObj.ADsPath
WScript.Echo "Parent is " & myObj.Parent
WScript.Echo "Schema is " & myObj.Schema

Running this script from the command line with cscript.exe will produce 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 are useful for identifying an object and where it is located in the directory hierarchy, but most of the useful information about an object is stored in other properties that are specific to that object's class. The following example will return the full name of a user given the username:

Dim myObj

Set myObj = GetObject("WinNT://mymachine/adsitest,user")
WScript.Echo "The full name for " & sUserName & " is " & myObj.FullName

This script produces output similar to the following:

The full name for adsitest is 'ADSI Test Account'

There is also an alternate syntax for retrieving property values. ADSI objects have a Get method, which may be used instead of the dot operator to read a given property. The following lines will produce the same result as the previous example:

Dim sFullName
Dim myObj

Set myObj = GetObject("WinNT://mymachine/adsitest,user")
sFullName = myObj.Get("FullName")
WScript.Echo "The full name for " & sUserName & " is " & sFullName

Refreshing the Local Cache

To avoid making unnecessary and slow network calls, ADSI caches properties locally. When you first bind to an object with GetObject, the object's properties are empty in the local cache. The first time you retrieve property values with the object.property syntax, or with the Get method, ADSI automatically retrieves all the property values for that object and places them in the local cache. All further retrieval of properties, using either syntax, will retrieve the values from the local cache.

You can explicitly fill an object's local cache values by calling the GetInfo method. The GetInfo method will query the namespace and refresh the cache with the values of all the properties on the object. GetInfo is called like this:

myObj.GetInfo

Setting Property Values

Setting properties is similar to getting properties, but with the syntax reversed. The following line will set the value of the user adsitest from the previous examples to Account for testing ADSI:

myObj.FullName = "Account for testing ADSI"

As in getting properties, setting properties may also be accomplished with an alternate syntax. The Put method may be used instead of the dot operator to set a given property. Put takes as its arguments the name of the property that should be set and its new value. The following code produces the same effect as the last example:

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

Unlike getting a property value, setting a property requires another step. You must call the SetInfo method to commit property changes to the directory service namespace:

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

It is very important to call SetInfo once you have made changes to the properties of an ADSI object; otherwise, those changes will only be made to the local cache, and not to the directory namespace. Forgetting to call SetInfo is a common mistake in ADSI programming.

Note that if you call GetInfo after making changes to properties, but before calling SetInfo, you will lose all those changes; GetInfo overwrites the property values in the local cache. The following script demonstrates the subtleties of SetInfo and GetInfo:

Dim sOriginalDescription
Dim myObj

Set myObj = GetObject("WinNT://mydomain/mymachine,computer")
sOriginalDescription = myObj.Description  ' Save original value for later

WScript.Echo "Values of myObj.Description property:"
WScript.Echo "Original Description:          " & myObj.Description

myObj.Description = "New description 1"
WScript.Echo "After setting, before GetInfo: " & myObj.Description

myObj.GetInfo
WScript.Echo "After GetInfo:                 " & myObj.Description

myObj.Description = "New description 2"
myObj.SetInfo
WScript.Echo "After SetInfo:                 " & myObj.Description

myObj.GetInfo
WScript.Echo "After second GetInfo:          " & myObj.Description

' Restore original value
myObj.Description = sOriginalDescription
myObj.SetInfo
WScript.Echo "Restored original value:       " & myObj.Description

Assuming that the value of the Description property on mymachine is "Just a computer", the results of running the previous script should look something like this:

Values of myObj.Description property:
Original Description:          Just a computer
After setting, before GetInfo: New description 1
After GetInfo:                 Just a computer
After SetInfo:                 New description 2
After second GetInfo:          New description 2
Restored original value:       Just a computer