COM+ Programming A Practical Guide Using Visual C++ and ATL [Electronic resources] نسخه متنی

COM+ Administration Object Model

The COMAdmin objects offer a simple object model for accessing the catalog.

The data stored in the catalog is treated as a hierarchy of collections. Collections serve as a container of homogeneous items. For instance, a COM+ application contains a collection of components; each component contains a collection of interfaces; each interface contains a collection of methods, and so on.

Each item in a collection exposes a set of properties that is consistent across the collection. For instance, every item in the Applications collection will expose a Name property, an AppId property, and so forth. Depending on how the properties are accessed, some properties are read-only while others can be read or written to.

Table 12.1 lists some of the collection types that are currently exposed through the COMAdmin object model.

The hierarchy of collection objects is shown in Figure 12.1.

Figure 12.1. Hierarchy of COM+ administrative collections. Adapted from [Pla-99].

Note that three collections are missing from the hierarchical representation: ErrorInfo, RelatedCollectionInfo, and PropertyInfo. This is because these three collections have special meaning and can be obtained from any other collection.

The ErrorInfo collection provides extended error information in case of failure while using COMAdmin methods to read or write to the catalog.

The PropertyInfo collection provides information about the properties that a specified collection supports.

The RelatedCollectionInfo collection provides information about other collections related to the collection from which it is called.

We will see the programming usage of these three collections later in the chapter.

In order to access the catalog, the collections in the catalog, the items in the collections, and the properties on these items, the COMAdmin library provides three (and only three) generic objects: COMAdminCatalog, COMAdminCatalogCollection, and COMAdminCatalogObject. Each object implements a dual interface, making it convenient to be used from early bound development tools as well as late bound development tools such as VB, VBScript, JScript, etc.

COMAdminCatalog Object

The COMAdminCatalog object is used to represent the catalog itself. It is the fundamental object that is used for any programmatic administration. It supports an interface, ICOMAdminCatalog, that provides methods to implement a variety of administrative tasks. Some of these tasks are listed below:

Connect to a catalog server, on either the local or the remote machine.

Retrieve various collections from the catalog.

Install, export, start, shutdown, and obtain information regarding COM+ applications.

Install or import single COM+ components, that is, components that are not part of any COM+ applications.

Start and stop COM+ services.

Table 12.2 describes some selected methods from ICOMAdminCatalog interface.

COMAdminCatalog can be instantiated using the PROGID COMAdmin.COMAdminCatalog, as shown in the following VBScript code fragment:

Set Catalog = CreateObject("COMAdmin.COMAdminCatalog")

When COMAdminCatalog is instantiated, it opens a session with the local catalog server. To open a session to a remote catalog server, the Connect method on the object can be called, as illustrated in the following VBScript code fragment:

Catalog.Connect("myremotemachinename")

We will cover some other methods later in the chapter.

COMAdminCatalogCollection Object

COMAdminCatalogCollection is a generic object used to represent any collection. It supports an interface, ICatalogCollection, that enables you to:

enumerate through the items contained within the collection

add or remove items to or from the collection

save or discard any pending changes made to the collection or to the items it contains

retrieve a related collection from the catalog

Table 12.3 describes some selected methods from the ICatalogCollection interface.

A collection can be obtained in two ways:

By calling GetCollection on the COMAdminCatalog object.

By calling GetCollection on the COMAdminCatalogCollection object.

Actually, GetCollection just sets up the returned list to be filled. The list is not filled until Populate (or its variants) is called, in which case the list gets filled up with the current items from the catalog. The usage is illustrated in the following lines of code:

set Applications = Catalog.GetCollection("Applications")
Applications.Populate

Populate can be called as many times as desired. Each call just synchronizes the list with the latest data from the catalog. Note that it is possible that some other application would have changed the collection that you are holding.

When a collection is retrieved, the data is actually stored in a transient cache. If an item is added, removed, or modified in the collection, the transient cache gets modified, not the actual catalog. To commit the changes to the catalog, you should call SaveChanges. After calling SaveChanges you would need to reload the collection list (by calling Populate), as shown in the following code fragment:

' Add a new appliction
Dim newApplication
Set newApplication = applications.Add
... ' Set various properties on newApplication
' Commit new application and reload the list
applications.SaveChanges
applications.Populate

It is possible that multiple programs may be working on the catalog simultaneously. While you are working on your transient copy of the data, someone else may have modified the catalog, either programmatically or through the Component Services snap-in. If there is any contention when the changes are being saved, the general rule is that the last writer wins, that is, the data stored in the catalog is the one that came from the last one to save it.

COMAdminCatalogObject Object

COMAdminCatalogObject is a generic object that can be used to represent any item contained in a collection. It exposes an interface, ICatalogObject, that can be used to:

obtain information about an item (in the collection) and its properties

modify the properties of the item

Table 12.4 shows some properties available on the ICatalogObject interface.

Each item in a collection has a name and a unique key. The key serves as the primary identifier for the item. In some cases it is a GUID, such as the CLSID for a component; in some cases it is the name of the item itself.

Each item in a collection contains properties that apply to that type of item. For example, every item in the applications collection represents an application object. Each application object has properties such as activation. (This property indicates if the application is a library application or a server application.)

Each property of a specific collection is uniquely identified by a name. The Value property on the ICatalogObject interface is used to obtain or save a specific named property exposed by an item.

The following VBScript code fragment lists each application installed on the local system. For each application, the code displays the applications key and whether the application is a library application or a server application.

' Instantiate a COMAdminCatalog object
Set Catalog = CreateObject("ComAdmin.COMAdminCatalog")
' Get the "Applications" collection and populate it
set Applications = Catalog.GetCollection("Applications")
Applications.Populate
' Display the name of each application
for each AppObject in Applications
DispString = AppObject.Name & " " & AppObject.Key
if AppObject.Value("Activation") = 0 then
DispString = DispString & " - INPROC"
else
DispString = DispString & " - LOCAL"
end if
wscript.Echo DispString
next

Some collections may expose the name and key of an item as properties as well. For example, the key of an application object can also be obtained as AppObject.Value("ID"). If you add a new object and save it with the key property of an existing object, you will overwrite the existing object.

Beware of setting the key property on an item. In most cases, it is better to let the catalog generate the key for you.

If a property is modified, the change is not committed until SaveChanges is called on the collection.

All the COMAdmin classes are served by one DLL ComAdmin.DLL. It can be found in the system32\COM subdirectory.