Page #125 (Programming Considerations)

< BACK  NEXT >

[oR]

Some Common Administrative Tasks

In this section, we will develop some simple VBScript -based programs to automate some common administrative tasks. To keep the code simple, I will assume that our administrative tasks will not fail; consequently, the error checking code is not written. The code is included on the CD. You may wish to add error checking yourself.

Uninstalling an Application

We will remove an application by its name.

An application belongs to the Applications collection. Let s obtain this collection first, as shown below:

 ' Create the catalog object  Dim catalog  Set catalog = CreateObject("COMAdmin.COMAdminCatalog")  ' Get the applications collection  Dim applications  Set applications = catalog.GetCollection("Applications")  applications.Populate 

Now, removing an application is as easy as iterating through the Applications collection, searching the application by its name, and removing the application once found.

 ' Remove an application identified by applicationName  Dim i, numPackages, bChanged  bChanged = False  numPackages = applications.Count  For i = numPackages - 1 To 0 Step -1    If applications.Item(i).Value("Name") = applicationName Then      applications.Remove (i)      bChanged = True    End If  Next 

As the name of an application is not unique, the code above attempts to remove all the applications that match the name.

Notice that we are iterating through the collection in a backward order. This is because when an item is removed from the collection, the COMAdmin library reindexes the items with higher indices downward to fill the removed item s place. Iterating backwards through the indices is the simplest way to reach each item exactly once.

Also notice the use of the boolean variable bChanged. Recall that the changes are not persisted back into the catalog until a SaveChange is called. Variable bChanged just offers us a little optimization in that we can commit the changes only if the named application was removed. The code fragment is shown below:

 ' Commit our deletions  If (bChanged = true) Then    applications.SaveChanges  End If. 

When an application gets removed, all of the components that belong to the application get unregistered. In addition, if an application was installed from an MSI file, the installation files will get deleted.

Installing an Application

Now let s develop a script to do the following operations:

• Install a library application named My Test Application

• Add a user role called Managers to the application

• Add a component with synchronization set to required, transaction set to required, and just-in-time activation enabled

Before installing an application, it is always a good idea to check if the application might already exist in the catalog. If it does, we need to remove such entries. Our earlier code to remove an application can be used here once again (which is why I dealt with uninstalling an application first).

The next step, as you have already guessed, is to fetch the applications collection and add the new application to the collection.

 ' Add the new appliction  Dim newApplication  Set newApplication = applications.Add  newApplication.Value("Name") = applicationName  newApplication.Value("Activation") = 0 ' Inproc=0, Local=1  applications.SaveChanges 

The possible choices for activation property are COMAdminActivationInproc and COMAdminActivationLocal. These enumeration constants, along with enumeration constants for many other properties such as synchronization, transaction, authentication, etc., are all defined in ComAdmin.idl and can be used directly in a C++ program. VBScript programmers, however, have to be content with using numeric values.

Once the application has been added to the catalog, performing any task on the application, such as adding components underneath it, requires us to obtain the key for the application. Do not forget to call Populate first on the just-saved collection. The code is shown here:

 applications.Populate  ' Get the application key  dim appKey  numPackages = applications.Count  For i = 0 To (numPackages - 1)    If applications.Item(i).Value("Name") = applicationName Then      appKey = applications.Item(i).Key    End If  Next 

To add a user-role to the application, we just get the related collection called roles for the application (identified by its key).

 ' Add a role called "Managers"  Dim roles  Set roles = applications.GetCollection("Roles", appKey)  roles.populate  Dim newRole  Set newRole = roles.Add  newRole.Value("Name") = "Managers"  roles.SaveChanges 

To install a component, the COMAdminCatalog object has a method, InstallComponent. The method takes four parameters. The first two parameters are the application key and pathname of the DLL containing the component. The third parameter specifies an external type library file. If there is no external type library, an empty string can be passed. The fourth parameter specifies the proxy/stub DLL for the component, if there is one. Otherwise, an empty string can be passed. The code is shown here:

 ' Install a component  catalog.InstallComponent appKey, _    "F: \MTAServer\Debug\MTAServer.dll" , "", "" 

The first parameter to InstallComponent can either be the application key or the name of the application.

In order to set any configuration on the just-added component, the components collection for the application has to be accessed, and the component has to be identified. For administrative tasks, a component is typically identified by its ProgID, as shown in the following code snippet:

 Dim components  Set components = applications.GetCollection("Components", appKey)  components.Populate  dim numComponents  numComponents = components.Count  for i = numComponents-1 to 0 step -1    if components.Item(i).Value("ProgID") = "MTAServer.MyTest.1" _    then      components.Item(i).Value("Synchronization") = 3      components.Item(i).Value("Transaction") = 3      components.Item(i).Value("JustInTimeActivation") = true    end if  next  components.SaveChanges 

The numeric values for synchronization and transaction settings can be obtained from ComAdmin.idl or from the SDK help documentation.

We are done installing an application.

This example provides the salient features of the COMAdmin programming model. Though these are just three object types they provide significant functionality and are easy to use.

Deploying an Application

Deploying an application that is installed on one machine to another machine requires the following three steps:

1. Create an installation package for the application

2. Copy the installation package to a network share directory that is accessible from the remote machine

3. Connect to the remote machine s catalog server and install the application from the installation package

To create an installation package, the COMAdmin library provides a method, ExportApplication, on the COMAdminCatalog object. When this method is called, COM+ generates Windows Installer (MSI) compatible installation image, which is a single file containing all the necessary pieces to install the application on another machine. This includes:

• The application s set of classes, components, and attributes at the application, component, interface, and interface method levels.

• All the DLLs and type libraries that describe the interfaces implemented by the application s classes.

In addition to the .msi file, ExportApplication creates a cabinet (CAB) file. This file, in effect, wraps the .msi file, allowing the users to download the application from a web browser such as Microsoft Internet Explorer.

In the following sample code, I create a MSI file, MyApp.MS I, from the application that I had installed earlier in the section:

 Dim applicationName  applicationName = "My Test Application"  ' Create the catalog object  Dim catalog  Set catalog = CreateObject("COMAdmin.COMAdminCatalog")  ' Export the app to a file  catalog.ExportApplication applicationName,  ".\MyApp.MSI", 0 

ExportApplication requires three parameters the application identifier (either the name or the key), the output file name, and a long value to specify some option flags. The option flags can be obtained from the SDK documentation. In the above code, I used a 0 value to indicate that I wish to export user-role information without exporting the actual list of users assigned to each role.

The second step of deployment is to copy the just-generated MSI file to a network share that is accessible to the remote machine.

The third step is to connect to the remote machine, using the Connect method, and install the application using the InstallApplication method. Both these methods are available on the COMAdminCatalog object. In the code snippet below, I install the application from the MyApp.msi file that is present on my local network share, \\PVDEV\MyNetShare, to a remote machine called PVDC.

 ' Connect to the remote catalog server  Dim catalog  Set catalog = CreateObject("COMAdmin.COMAdminCatalog")  catalog.Connect "PVDC"  ' Install the app from the file  catalog.InstallApplication "\\PVDEV\MyNetShare\MyApp.MSI" 

When a COM+ application is installed from an MSI file, the Windows Installer extracts the necessary files into the \Program Files\COMPlus Applications\{AppKey} directory, where AppKey is a GUID unique to the application. The installer also adds an entry in the Add/Remove Programs control panel.

< BACK  NEXT >