Page #123 (Overview)


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.

Table 12.1. COMAdmin Collections




List of all COM+ applications installed on the local machine


List of all components in an application


List of all the protocols used by DCOM


Extended error information when a method on any COMAdmin object fails


List of all the in-process COM servers registered with the system


List of all the interfaces exposed by a component


List of computer-level settings information


List of all the methods on an interface


List of all the properties that a specified collection supports


List of other collections related to the collection from which this method is called


List of roles for an application


List of users in a role

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.

Table 12.2. Selected Methods From Interface ICOMAdminCatalog



Administrative Methods


Opens a session with the catalog server on the specified machine


Retrieves the specified collection


Retrieves any collection anywhere in the hierarchy

Component Methods


Places an already registered component into the catalog


Installs a new component into the catalog


Retrieves information about one or more components

Application Methods


Shuts down a running server application


Produces a self-contained installation file (.MSI) for installing the application onto other machines


Reads an MSI file and installs the application

Services Methods


Starts the load-balancing router service (if installed)


Stops the load-balancing router service (if installed)


Starts the in-memory database service (if installed)


Stops the in-memory database service (if installed)


Checks the status of a COM related service

Events Method


Installs an event class into an application


Gets a list of event classes matching the specified interface

Backup Methods


Backup RegDB into a file


Restore RegDB from a file

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:


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.

Table 12.3. Selected Methods From the ICatalogCollection Interface



Populate the collection


Reads in current data from the catalog for all objects in the collection


Reads in data only for the specified objects


Reads in data for the objects matching the query. Not implemented in the current release

Information Retrieval


Obtains the number of items in the collection


Obtains an item given its index from the collection


Obtains an enumerator for the collection

Item Manipulation


Adds a new element to the collection


Removes a specified element from the collection


Saves any changes made to the collection or its objects

Related Collection


Gets a collection related to this collection s specific object

A collection can be obtained in two ways:

  1. By calling GetCollection on the COMAdminCatalog object.

  2. 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.

Table 12.4. Selected Properties From the ICatalogObject Interface




Gets the name of the item


Gets the unique ID of the item


Gets or sets a named property on the item

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 application s 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.


COM+ Programming. A Practical Guide Using Visual C++ and ATL
COM+ Programming. A Practical Guide Using Visual C++ and ATL
ISBN: 130886742
Year: 2000
Pages: 129 © 2008-2017.
If you may any questions please contact us: