Metabase Connections in ABO
Active Base Objects (ABO) connect to nodes in the metabase to make configuration changes. It is recommended that you read IIS Configuration using the Metabase and Metabase Structure before connectin to the IIS metabase through ABO.
Handles to Keys
ABO views the metabase as a collection of keys and data. A KeyType property is set on each key to identify its class type. Class types are similar to IIS admin objects. To connect to a key in the metabase, ABO uses handles.
When the metabase is initialized at startup, a handle to the metabase called METADATA_MASTER_ROOT_HANDLE is automatically opened with read-only permissions. You can use the OpenKey method to get a handle to a key in the metabase by providing the key's path relative to this handle, such as /LM/W3SVC/2, the path to the key for the second Web server. You can also use a handle to any key as a reference point to its subkeys. For example, if you have opened a handle to /LM/W3SVC/2, you can then use this handle and the relative path, /ROOT/VDir1, with the OpenKey method to get a handle to the key /LM/W3SVC/2/ROOT/VDir1.
Note
Each key name cannot be longer than the METADATA_MAX_NAME_LEN constant. This applies to each node name separately, not the entire path. In the preceding examples, the names LM, W3SVC, and VDir1 must each be less than METADATA_MAX_NAME_LEN, but their combined path, /LM/W3SVC/2/ROOT/VDir1, can be longer, though it is not recommended when using a long path name in the OpenKey method. When creating new sites and virtual directories, remember this rule when naming them.
Once you have a valid handle to a key, you can use the ABO methods to manipulate that key's data entries. You can use the GetData method to retrieve a data entry, or the SetData method to add or modify an entry to the metabase. The GetAllData method enables your application to retrieve all, or a subset of, the values associated with a key by using a single method call. The EnumData method enables your application to enumerate all, or a subset of, the values associated with a key. When a data entry is no longer needed, you can remove it from the metabase by calling the DeleteData method.
In addition to manipulating data entries, you can add, delete, or move keys from one path to another in the metabase. Use the AddKey method to add keys and the DeleteKey method to delete keys in the metabase. Use the CopyKey method to copy a key and all of its subkeys and data items.
Locking the Metabase
The master handle, METADATA_MASTER_ROOT_HANDLE, does not protect metabase data from multiple-thread access, so data might change unexpectedly in the metabase. To insure consistency of metabase data by preventing other threads from changing configuration data, always use the OpenKey method. A handle opened with the OpenKey method locks the metabase data for that key, all of its parent keys, and all of its subkeys.
A handle opened with read-only permission to a key permits other application processes to open read-only handles to that key and other keys in its path, both parent keys and subkeys. A handle opened with write permission, does not permit another application process to open a handle with write permission to that key until all handles, read-only or write, have been closed by all application processes to all keys in that path. Because server performance can significantly be reduced while waiting for keys to be available for read-only handles, it is recommended that you call the CloseKey method as soon as you have finished writing data. This frees the handle and releases that key, and also its parent keys and subkeys, to other application processes.
In contrast, the methods of the ADSI and WMI providers for IIS, which are wrappers around ABO, do not lock the metabase for extended periods of time. Data is not written to the metabase until the SetInfo ADSI method or the Put_ WMI method is called, which immediately writes all configuration changes that are stored in object variables.