Easy Active Directory Scripting for Systems Administrators, Part 2

Let's apply your newfound knowledge to a modified version of the easyadsi.vbs script that I introduced in Part 1. I use the code in Listing 2, page 176, as the basis for the discussion that follows. Rather than walking through the script line-by-line, I explain each IADs method, then identify an example of the method in Listing 2. However, I don't use all the available IADs methods because Listing 2 is what you might use in the real world (in which you rarely use several of the IADs methods).

GetInfo. GetInfo retrieves an object's properties from AD and loads the property values into the local property cache to initialize it. GetInfo loads into the cache only those properties that contain values.

Listing 2 doesn't use the GetInfo method for two primary reasons. First, I create a new user object at callout A in Listing 2, so I wouldn't invoke GetInfo on an object that doesn't yet exist. And although I update several existing properties at callout B in Listing 2, I'm not concerned with the previous property values. You don't need to initialize the cache with existing values if you plan to overwrite the values (unless you want to save the old values for some reason, such as for change management).

The only case for which you can justify a call to GetInfo in Listing 2 is if you want to verify the new values set at callout B. To do so, call GetInfo after calling SetInfo to refresh the values in the cache. If you call GetInfo before SetInfo (and after the Put statements), GetInfo overwrites the cached values (which you used Put and PutEx to modify) with the original or old values in the directory, and your changes are lost.

Although using GetInfo is a valid way to refresh the cache, the method isn't the most efficient one. For example, I update three properties at callout B in Listing 2. Calling GetInfo after callout B retrieves all values for the more than 50 properties set in callout A in Listing 2. Using GetInfoEx instead of GetInfo would be a more efficient approach and use of your network.

GetInfoEx. GetInfoEx also initializes the local property cache by retrieving an object's properties from AD and loading the property values into the cache. However, GetInfoEx loads only those properties listed in the property array, which you provide as the first parameter to GetInfoEx. GetInfoEx is therefore a more efficient method of refreshing updated values. However, as is the case with GetInfo, be sure to call SetInfo before you call GetInfoEx with the name of an updated property.

GetInfoEx is also a more efficient method than GetInfo for checking an existing value. For example, if you want to verify the value of one property in AD, use GetInfoEx. Rather than explicitly calling GetInfo or using Get to implicitly call GetInfo (which I discuss later in the article), pass GetInfoEx an array that contains one element that identifies the property you want to check.

Another situation that calls for GetInfoEx results from ADSI not loading operational attributes (e.g., canonicalName) into the cache. You must use GetInfoEx to explicitly request an operational attribute before you read it, as the code in Figure 3, page 180, shows. Otherwise, you'll receive the error message The Active Directory property cannot be found in the cache.

Get and GetEx. Get and GetEx provide similar functions in that both read specified values from the local property cache. Both methods also invoke an implicit GetInfo call when the property cache isn't initialized. You should therefore use GetInfoEx to minimize network traffic if you're interested only in retrieving a subset of values. After the property cache is initialized either explicitly or implicitly, you can't use Get or GetEx to refresh the cache.

Get returns single-value properties as scalar variants and multivalue properties as variant arrays. GetEx returns all property values as variant arrays, so it returns a single-value property in a single-element array.

Using Get is slightly more efficient than using GetEx if you know whether the target property is a single-value or multivalue property. However, using Get can be tricky when you're not certain about the value because you'll need to check Get's return type to ensure you dereference the data correctly. Otherwise, your script will encounter a runtime error if you handle a scalar as an array, or vice versa. To complicate matters further, Get returns a multivalue attribute that contains a single value as a scalar variant and not as a single-element array. Given Get's caveats, GetEx can be slightly easier to use because you can use the same approach to handle all property data. You don't need to check the return type because GetEx returns all data in an array.

The code in Listing 2 doesn't call Get or GetEx because these methods aren't necessary to the script's purpose and because the script doesn't produce console or file output. If I want to echo the property values, I need to include the appropriate output statement followed by the same object.propertymethod syntax that I used to set the property values at callout A in Listing 2. The code that Figure 3 shows provides an example of the object.propertymethod syntax that you use in conjunction with the Wscript .Echo statement.

Put and PutEx. You use the Put method to write single-value properties to the property cache and PutEx to append, modify, replace, and clear multivalue properties in the property cache. Put and PutEx write or modify values in the property cache only. You must call SetInfo to write the changes in the cache to AD. Although you can use Put to modify multivalue properties, the method doesn't give you any control over the properties' existing data. Put will blindly replace all existing multivalue data in the same way that it replaces a single-value property. You use PutEx in situations in which you need to preserve existing data in a multivalue property.

As Table 2 shows, PutEx uses a control code to communicate the type of update to perform. ADS_PROPERTY_ APPEND appends a new value while preserving existing values. ADS_PROPERTY_ DELETE deletes a specified value and leaves other values intact. Similarly to Put, ADS_PROPERTY_UPDATE replaces all existing values with new values, and ADS_PROPERTY_CLEAR removes all values to clear a property.

Callout B in Listing 2 demonstrates the use of Put and PutEx. In the case of PutEx, I append a new value to the otherHomePhone attribute. (Note that you have no control over the order of values in multivalue properties.)

SetInfo. SetInfo writes new or modified property values from the cache to AD. SetInfo is always an explicit call; when the property cache isn't initialized, SetInfo is never implicitly invoked the same way that Get or GetEx invokes GetInfo. Any property value changes that you use Put or PutEx to make are lost if you invoke GetInfo or possibly GetInfoEx before calling SetInfo. You can use one SetInfo call to batch multiple changes, but if you do so, you need to understand that SetInfo is an all-or-nothing operation. That is, SetInfo writes all changes leading up to the SetInfo call to the directory, or makes no changes if an error occurs (e.g., you encounter a constraint violation, you run into a security concern).

The object.propertymethod syntax convention. The object.propertymethod syntax is a convention that automation clients can use instead of Get and Put. The syntax lets Visual Basic (VB) and VBScript programmers use the familiar dotMethodOrPropertyName notation. The syntax has two parts separated by a dot (.). The name to the left of the dot is the object reference; the name to the right of the dot is the attribute's Lightweight Directory Access Protocol (LDAP) display name to retrieve or write in the cache. Using the object.propertymethod syntax on an assignment operator's right side or in an expression results in a Get. Using the syntax on an assignment operator's left side results in a Put. The object.propertymethod syntax's behavior is identical to that of Get and Put (i.e., Get's return types and Put's limitation in updating multivalue properties).

I use the object.propertymethod syntax throughout callout A in Listing 2 to set the initial values for both single- and multivalue properties. In callout B in Listing 2, I switch to using Put and PutEx because I update the multivalue property named otherHomePhone.

   Previous  1  [2]  3  Next