Step 1: Establishing a Connection

Microsoft® Windows® 2000 Scripting Guide

« Previous | Next »   

Figure 5.1 and all of the preceding listings demonstrated that the first step you must take to complete any scripted directory management task is connecting to an object. This initial step is referred to as binding to the directory. Binding to the directory prepares the script to operate on an object.

When creating or deleting an object, you must bind to the container object where a leaf object will be created or deleted. When reading or modifying an object, you must bind to the object that you want to read or modify.

Because the first part of this chapter focuses on Active Directory, the examples shown here demonstrate how an ADSI script binds to Active Directory.

Choosing a Directory Service Object for a Binding Operation

To determine which directory service object to specify in a binding operation, consider the task you want to complete (create, delete, read, or modify), the type of object (leaf or container), and, if the object is a container, whether it is empty. Figure 5.2 shows a data flow diagram to help you determine which directory service object to use for a binding operation.

Figure 5.2   How To Determine Which Directory Service Object to Use for a Binding Operation

How To Determine Which Directory Service Object to Use for a Binding Operation

The data flow diagram does not show the following two tasks that can also be scripted:

• Deleting a container that is not empty.

  Using the DeleteObject method, you can quickly and irreversibly delete a container that is not empty. This is potentially dangerous, so exercise caution before performing this type of delete operation.

• Moving objects from a container before deleting it.

  You might need to delete a container but preserve its contents by moving them elsewhere.

For information about how to script object moves, see "Moving and Renaming Objects" later in this chapter.

Performing a Binding Operation

To bind to an Active Directory object, you use the VBScript GetObject function, the prefix LDAP: followed by two slashes, and the path to a directory object. The binding statements in four of the previous listings are:

• Set objDomain = GetObject("LDAP://dc=NA,dc=fabrikam,dc=com")

  Binds to the na.fabrikam.com domain.

• Set objOU = GetObject("LDAP://ou=HR,dc=NA,dc=fabrikam,dc=com")

  Binds to the HR OU in the na.fabrikam.com domain.

• Set objUser = _

      GetObject("LDAP://cn=MyerKen,ou=HR,dc=NA,dc=fabrikam,dc=com")

  Binds to the MyerKen user account in the HR OU of the na.fabrikam.com domain.

• Set objGroup = _

      GetObject("LDAP://cn=Atl-Users,ou=HR,dc=NA,dc=fabrikam,dc=com")

  Binds to the Atl-Users group in the HR OU of the na.fabrikam.com domain.

ADsPath

In ADSI terminology, the LDAP: prefix combined with the path to a directory object is called an ADsPath. The binding code examples appearing in the preceding section show ADsPath strings enclosed in parentheses.

Specifying the provider

The first part of the ADsPath identifies an ADSI provider. ADSI scripts use providers to communicate with different types of directory services. For example, ADSI scripts use the ADSI Lightweight Directory Access Protocol (LDAP) provider (Adsldp.dll) to communicate with Active Directory and other LDAP version 2.0 compliant and version 3.0 compliant directory services. To communicate with the local Security Accounts Manager (SAM) database, ADSI scripts use the ADSI WinNT provider (Adsnt.dll). The LDAP: prefix at the beginning of the ADsPath identifies the ADSI LDAP provider as the appropriate provider for completing the binding operation.

Note

• ADSI provider identifiers are case sensitive.

The VBScript GetObject function uses the provider identifier to locate and load the appropriate ADSI provider dynamic-link library into memory. Once the provider is loaded into memory, the second part of the ADsPath, the path to the directory object, tells the provider which object to bind to in the directory.

Specifying the directory object s path

The second part of the ADsPath is the path to the target object in the directory. ADSI supports several object path formats; the path format used in all of the preceding scripting examples is referred to as an object s distinguished name (DN). This is just one of a number of identifiers that you can use to build an object s ADsPath. For more information about ADSI identifiers and how to use them to refer to objects in Active Directory, see "Root Directory Service Entry" later in this chapter.

Every object stored in Active Directory has a distinguished name. Think of an object s distinguished name as the LDAP version of a file s fully qualified path. Every file has a fully qualified path that consists of a device name, followed by zero or more folder names, followed by the file name. Likewise, objects are located within Active Directory according to a hierarchical path. The full path to the object is defined by the object s distinguished name.

Similar to a file path that contains multiple folder names separated by backslashes, an object s distinguished name contains a series of attribute=value pairs separated by commas. Each attribute=value pair in an object s distinguished name is analogous to a single folder in a file s fully qualified path.

The attribute part of each attribute=value pair identifies an attribute type, which is defined in RFC 2247 and RFC 2253 and is based on the class of object. For example, the attribute type for a user account (User class) is CN, and the attribute type for an organizational unit (organizationalUnit class) is OU.

Note

• With the exception of the Domain Controllers container, the attribute type of the default containers directly below an Active Directory domain, such as the Computers, Users, and Built-in containers, is CN rather than OU.

The value part of each attribute=value pair is the name you provide when you create the object. Consider the MyerKen user account located in the HR OU of the na.fabrikam.com domain. Table 5.1 shows the object class from which each component of the DN is derived, along with its attribute type and value.

Table 5.1   Object Class, Naming Attributes, and Values

Object Class	Attribute Types	Value
User	CN	MyerKen
organizationalUnit	OU	HR
domain	DC	NA
domain	DC	fabrikam
domain	DC	com

The entire string of attribute=value pairs represents the path from an object to the root of the directory tree. Following each attribute=value pair from left to right moves you up through the directory hierarchy, as shown in Figure 5.3.

Figure 5.3   Example Directory Hierarchy and the DN of a User Account Object

Example Directory Hierarchy and the DN of a User Account Object

The MyerKen user account is located in the HR OU in the NA child domain. The parent domain of NA is fabrikam.com. Fabrikam.com is the root domain of the Active Directory hierarchy. Thus, the binding string (ADsPath) to this object is:

"LDAP://cn=MyerKen,ou=HR,dc=NA,dc=fabrikam,dc=com" 

Note

• The binding string used in Listing 5.1 is a little different from the other listings because it employs a special ADSI feature called rootDSE. Ultimately, though, the binding string in Listing 5.1 also resolves to a distinguished name. For information about the rootDSE feature, see "Root Directory Service Entry" later in this chapter.

Creating an Object Reference to the Directory Object

The last part of the binding step to explore is the code on the left side of the assignment operator (equal sign), the VBScript Set keyword followed by a variable name that you provide. For example, the variable names objDomain, objOU, objUser, and objGroup appear in the earlier listings.

In contrast with simple string and numeric assignment statements, you must use the VBScript Set statement to associate an object reference with (or assign it to) a variable. The Set statement appears in the binding step because the GetObject function requires this in order to return a reference to an object.

In the case of ADSI, the object reference returned by GetObject is a virtual representation of the Active Directory object defined by the ADsPath in the binding step. The Set statement assigns the object reference to the variable following the Set keyword. For example, the objUser variable appearing in earlier listings is a virtual representation of the MyerKen user account object. Think of the variable as the script s pointer, or reference, to the virtual representation of the Active Directory object. The script then uses the variable to manage the referenced object.

Now that you have determined the object to bind to and have completed step 1 (binding to the object) you can perform a task against the object.

---

 Send us your feedback

« Previous | Next »