Easy Active Directory Scripting for Systems Administrators, Part 2

In "Easy Active Directory Scripting for Systems Administrators, Part 1," September 2000, I discussed that you need only 3 of the more than 50 Active Directory Scripting Interfaces (ADSI) to accomplish 80 percent of your Active Directory (AD) scripting tasks. Part 1 examined one of the three core interfaces, IADsOpenDSObject. You'll recall that the IADsOpenDSObject interface exposes the OpenDSObject method that you use to authenticate your connection to AD. Part 1 also included an overview of AD and ADSI terminologies and distinguished names (DNs). Part 2 covers the remaining core interfaces—IADs and IADsContainer.

The Keys to ADSI Scripting
Before we examine the IADs and IADsContainer interfaces in detail, let me emphasize their importance. You can't accomplish even simple ADSI scripting tasks without encountering one or both of these interfaces. You use the properties and methods that IADs and IADsContainer provide to create, delete, and modify almost every AD object. Therefore, I encourage you to commit the two interfaces to memory if you're serious about ADSI scripting. These interfaces involve only half a dozen interface properties and about a dozen methods, so the task isn't as overwhelming as you might think.

The IADs Interface
IADs is the identity interface, and every AD object implements IADs. IADs exposes six properties and seven methods. The six IADs properties that Table 1, page 174, lists provide important identity information about an object.

Let's examine a few scenarios in which you might use the IADs properties. Suppose you want to use the ADSI OLEDB/ADO provider and query AD, then subsequently modify the objects returned in the query results. However, the record set that the ADSI OLEDB/ADO provider returns is read-only, so you need to bind to each object in the query results before you can modify the object. To do so, you must have a valid ADsPath to perform the bind operation. Because every object exposes its ADsPath through the IADs interface, you can identify ADsPath as one of the values to return in the query results. Returning the ADsPath is a best practice to follow whenever you query AD.

You can use the Class property to determine an object's schema class (e.g., computer, organizational unit—OU, group, user), which is useful for filtering operations. For example, if you enumerate nested groups, you can check the Class property inside a loop to determine when you encounter a group versus a user and respond accordingly.

The globally unique ID (GUID) is the only object property that never changes. You use the GUID property to bind to an object in a way that is protected against move and rename operations. The Name property is the object's relative distinguished name (RDN); it represents the object's primary name and uniquely identifies an object in its current container. You can use the Parent property with the ADsPath and Schema properties to walk the entire Directory Information Tree (DIT).

You use the Schema property to create a reference to an object's schema class to determine an object's mandatory and optional properties, as Listing 1, page 174, shows. (You can download complete listings from Windows 2000 Magazine's Web site at http://www.win2000mag.com/. Enter 15734 in the InstantDoc ID text box, and click the 15734.zip file.) After binding to the target object, I echo the values of the six IADs properties at callout A in Listing 1. At callout B in Listing 1, I use the path that the object's Schema property provides to bind to the object's schema class. In return, I get a reference to the schema's user class definition based on the object type that I connected to in the first line of Listing 1. After I get the reference, I simply echo the contents of the user class attributes mustContain and mayContain. Figure 1, page 175, shows a portion of Listing 1's output.

The seven IADs methods shown in Table 2, page 175, provide the mechanisms that you use to add, modify, and delete an object's data. Although the IADs methods are easy to use, some of the usage scenarios can be tricky. However, before I discuss those scenarios, you need to understand the ADSI property cache.

The ADSI property cache is a local memory buffer that temporarily stores attribute values while your script is creating, modifying, or reading them. The purpose of the cache is to minimize the impact on the network by reducing the number of network round trips that might otherwise occur when you manage a large number of objects and attributes. The cache batches multiple read and write operations into one or a small number of network transactions to accomplish its goal. This process ensures that the majority of your scripts' read and write operations are carried out on the client workstation (i.e., the workstation on which your script is running).

The property cache is a per-object address space that ADSI allocates when you bind to an object. However, the cache is initially empty. You use IADs methods to initialize and interact with the values in the local property cache and the underlying directory, as Figure 2, page 176, shows.

Of the seven IADs methods, only GetInfo, GetInfoEx, and SetInfo explicitly interact with the underlying directory. Get, GetEx, Put, and PutEx interact only with values in the property cache, with one exception that I discuss later. The process you use to work with an object's data and the property cache largely depends on the task at hand. For example, if you want to create an object and initialize its properties, perform the following four steps:

1. Use VBScript's GetObject function to bind to the target container that will hold the new object (network traffic).
2. Use the IADsContainer Create method to create the new object in the local property cache (no network traffic).
3. Use the IADs Put or PutEx methods, or both, to set the new object's mandatory and optional properties in the local property cache (no network traffic).
4. Use the IADs SetInfo method to commit (write) the new object and corresponding properties in the property cache to the directory (network traffic).

If you want to read and modify an existing object's properties, perform the next six steps:

1. Use VBScript's GetObject function to bind to the target object (network traffic).
2. Use the IADs GetInfo or GetInfoEx method to retrieve the object's properties from the underlying directory to prime (initialize) the local property cache (network traffic).
3. Use the IADs Get or GetEx methods, or both, to read the desired properties in the local property cache (no network traffic).
4. Use the IADs Put or PutEx methods, or both, to modify the desired properties in the local property cache (no network traffic).
5. Use the IADs SetInfo method to commit (write) the modified properties in the property cache to the directory (network traffic).
6. Use the IADs GetInfo or GetInfoEx method to reinitialize the local property cache, thereby reflecting the changes you made in Step 5 (network traffic).

   Previous  [1]  2  3  Next