Automating Microsoft Transaction Server Deployment

Microsoft Corporation

June 1997

Abstract

This document describes how you can use the scriptable administration objects to automate deployment and distribution of your Microsoft® Transaction Server (MTS) packages.

The Microsoft Transaction Server Explorer

The MTS Explorer lets you configure and deploy packages by using a graphical user interface rather than through programming code. However, if you would like to automate steps in the MTS Explorer, you can use the scriptable administrative objects to program configuration and deployment tasks. Note that the scriptable administrative objects support the same collection hierarchy as the MTS Explorer. The following figure shows the MTS Explorer collection hierarchy.

Figure 1. The Microsoft Transaction Server Explorer collection hierarchy.

For more information about MTS Explorer functionality, refer the Microsoft Transaction Server Administrator’s Guide Help.

Using the Scriptable Administration Objects

Microsoft Transaction Server scriptable administration objects are OLE automation objects that you can use to program administrative and deployment procedures, including:

Installing a Pre-Built Package
Creating a New Package and Installing Components
Enumerating Through Installed Packages to Update Properties
Enumerating Through Installed Packages to Delete a Package
Enumerating Through Installed Components to Delete a Component
Accessing Related Collection Names
Accessing Property Information
Configuring a Role
Exporting a Package
Configuring a Client to Use Remote Components

Note that you can use the scriptable administration objects to automate any task in the MTS Explorer.

The scriptable administration objects are derived from the IDispatch interface, so you can use any Automation language to develop your package, such as Microsoft Visual Basic version 5.0, Microsoft Visual C++ version 5.0, Microsoft Visual Basic Scripting Edition, and Microsoft JScript.

Each folder in the MTS Explorer hierarchy corresponds to a collection stored in the catalog data store. The following scriptable objects are used for administration:

Catalog
CatalogObject
CatalogCollection
PackageUtil
ComponentUtil
RemoteComponentUtil

The Catalog, CatalogObject, and CatalogCollection scriptable objects provide top-level functionality such as creating and modifying objects. The Catalog object enables you to connect to specific servers and access collections. Call the CatalogCollection object to enumerate, create, delete, and modify objects, as well as to access related collections. CatalogObject allows you to retrieve and set properties on an object. The Package, Component, Remote Component, and Role objects enable more specific task automation, such as installing components and exporting packages. This utility layer allows you to program very specific tasks for collection types, such as associating a role with a user or class of users.

The following diagram illustrates how the MTS SDK scriptable administration objects interact with the MTS Explorer catalog:

Interface	Description
ICatalog	The Catalog object enables you to connect to specific servers and access collections.
ICatalogCollection	The CatalogCollection object can be used to enumerate objects, create, delete, and modify objects, and access related collections.
ICatalogObject	The CatalogObject object provides methods to get and set properties on an object.
IPackageUtil	The IPackageUtil object enables a package to be installed and exported within the Packages collection.
IComponentUtil	The IComponentUtil object provides methods to install a component in a specific collection and to import components registered as an in-proc server.
IRemoteComponentUtil	You can use the IRemoteComponentUtil object to program your application to pull remote components from a package on a remote server.
IRoleAssociationUtil	Call methods on the IRoleAssociationUtil object to associate roles with a component or component interface.

For example, you can automate the steps in the MTS Explorer for creating a new package and installing components into the new package by using the scriptable objects in the utility layer (Package, Component, Remote Component, and Role objects).

The following Visual Basic sample shows how to use the scriptable administration objects to create a new package named “My Package” and install the components in that package.

Declare the objects that you will be using to create a new package and install components into that package.

Dim catalog As Object
Dim packages As Object
Dim newPack As Object
Dim componentsInNewPack As Object
Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.
```
On Error GoTo failed
```
Call the CreateObject method to instantiate the Catalog object. Retrieve the top level Packages collection from the CatalogCollection object by calling the GetCollection method. Then call the Add method to add a new package.
```
Set catalog = CreateObject("MTSAdmin.Catalog.1")
Set packages = catalog.GetCollection("Packages")
Set newPack = packages.Add
Dim newPackID As String
```
Set the package name to “My Package” and save changes to the Packages collection.
```
newPackID = newPack.Key
newPack.Value("Name") = "My Package"
packages.savechanges
```
Call the GetCollection method to access the ComponentsInPackage collection. Then instantiate the ComponentUtil object in order to call the InstallComponent method to populate the new package with components.
```
Set componentsInNewPack = packages.GetCollection("ComponentsInPackage", newPackID)
Set util = componentsInNewPack.GetUtilInterface
util.InstallComponent"d:\dllfilepath", "", ""
Exit Sub
```
Use the Err object to display an error message if the installation of the package fails.
```
failed:
    MsgBox "Failure code " + Str$(Err.Number)

End Sub
```

For a complete description of how to program these procedures and more sample code, refer to the Scriptable Administration section of the Microsoft Transaction Server documentation.