Automating Microsoft Transaction Server Client Installation

Microsoft Corporation

June 1997

Abstract

This article describes how you can use the client install utility to automatically generate installation executables for clients of Microsoft® Transaction Server (MTS) applications. You can obtain the client install utility that generates these executables from MTS 1.1, which is available for download from http://www.microsoft.com/transaction/. See the MTS 1.1 Readme file for late-breaking information and known limitations of the client install utility.

Distributing Server Applications

The client install utility automates distribution of server applications to Distributed Component Object Model (DCOM) clients via the same package export mechanism used to export server applications to servers. Exporting a package generates the necessary files for distribution to servers as well as clients.

You can distribute your MTS application to multiple server and client computers by importing and exporting your package using the MTS Explorer. The client install utility lets you use the MTS Explorer to generate client install executables that can be distributed from a Web page, shared directory, or electronic mail. To demonstrate automatic client installation of server applications, follow these steps using the MTS Explorer to create a client install executable for the MTS Sample Bank:

1. Install the Sample Bank application if you have not already done so.
   
   
2. Export the Sample Bank package from the server on which your server application is installed. Specify "c:\mtx\test\bank.pak" as the package export filename (replace "c:\mtx" with your MTS directory if it differs).
   
   
3. Locate the folder into which you exported the bank.pak package. You will see a subdirectory called \clients that contains a single file named "bank.exe". Do not run the bank.exe file on your server computer. This executable file is a self-extracting, self-installing bundle of all the information necessary for a client computer to use your server application remotely via DCOM.

You can distribute these client install executables just like any executable file, including via shared directory, electronic mail, intranet HTML web page, or Microsoft System Management Server.

When executed from a client computer, the client install executable file copies the necessary proxy-stub DLLs and type libraries to that computer, and updates the client's system registry with information required by DCOM, including the name of the server computer itself. Client applications can now take advantage of your server package from that client computer.

Developing Applications for the Client Install Utility

The requirements for using the client install utility should be considered during the design, development, and deployment of your server package. In order for administrators to generate client install executables for existing MTS applications, the components in the package must meet the following requirements:

• Components and their interfaces are described by type libraries
  
  
• Components have programmatic identifiers (ProgIDs) and a type library or MIDL-generated custom proxy-stub DLL exists for marshaling each exposed interface in the package.

Essentially, packages of components that meet the minimum requirements for running in MTS can be exported to create client installation executables.

It is recommended that you ensure that only required client-specific code is distributed to your client computers. Not all components in your package may be called directly by clients. Some components are called only by other components running in a separate package on the server. To ensure that only the required code is distributed to clients, export a server and client version of your package by following these steps:

1. Export the complete package, which represents your server installation.
   
   
2. Delete all of the server-only components in your package.
   
   
3. Export the package again to a different location. This second export involves only the components that clients call directly.

An administrator first installs the client-only version of your package. Then the administrator exports the package to generate a client install executable. The client-only version of the application can be deleted and the server version installed.

Note that development tools supporting ActiveX™ components may merge your type library or proxy-stub DLL into your implementation DLL. If you do not want to distribute your implementation DLL to client computers, keep your type libraries and proxy-stub DLLs separate from your implementation DLLs. For example, Visual Basic® 5.0 allows you to create a separate type library by clicking the Remote Server Files option. The client only needs a type library or custom proxy-stub DLL to use your server package remotely. However, if the type library or custom proxy-stub DLL is merged into your implementation DLL, the client install executable file must include that entire DLL.

Generating the Client Install Executable

Administrators can create an automated client installation for an application by simply exporting the package. Exporting a package generates a \clients subdirectory beneath the directory to which you exported the package. The \clients subdirectory contains a single executable with the name specified during package export. When run on any client supporting DCOM, the executable installs all the necessary information for clients on that computer to use the server application remotely.

When exporting and installing packages, follow these rules:

• Never run the client executable file on the server computer. Doing this wipes out the registry entries required to run the server package. If you make this mistake, you must remove the application using the Add/Remove Programs option in the Control Panel (remote applications begin with "Remote Application" in the Install/Uninstall list). Then delete and re-install the package using the MTS Explorer.
  
  
• Export the package after the package has been installed on the server computer that you want your clients to use. The generated client install executable always directs clients of the server package to that server computer.
  
  
• If any of the server package globally unique identifiers (GUIDs), including class, interface, or type library identifiers, used by clients are changed by the developer, you will need to re-export the package to generate an updated client install executable. All clients will be broken until they run the new client install executable. Note that some development tools (such as Microsoft Visual Basic) may change these GUIDs without notifying the developer.
  
  
• Do not specify a package file that included spaces in the file name or path; this will prevent client install executables from being generated. Client install executables must not include spaces, even though the files distributed by the executable may contain spaces in their names.

Distributing the Client Install Executable

The client installation executable automates installing the information that allows client computers to use a server package remotely via DCOM. (Note that if a remote application returns an interface that is defined outside the exported package, the client executable for the application will not install the marshaling information for that interface.)

The client install executable also allows the remote application to be removed from the client computer via the Add/Remove Programs option in the Windows Control Panel.

The client install executable automates the following steps:

1. Copies the client install executable to a temporary directory named \clients and extracts the necessary client-side files, including type libraries and custom proxy-stub DLLs.
   
   
2. Transfers type libraries and proxy-stub DLLs for the server package to the Remote Applications folder in the Program Files folder. All remote applications are stored in the Remote Applications folder. Each remote application has an individual folder named by the package GUID.
   
   
3. Updates the system registry with the required entries for clients to use the server package remotely via DCOM, including information related to application, class, programmatic, interface, and library identifiers.
   
   
4. Registers the application in the Add/Remove Programs option in the Control Panel so that the application can be uninstalled at a later date. All remote applications are prefaced with "Remote Application" so that you can easily find your application in the Add/Remove Programs list of installed components.
   
   
5. Removes the \clients subdirectory and files generated during install.

The client install executable can be distributed in a variety of ways, including:

• Shared directory
  
  
• E-mail attachment
  
  
• HTML in any of the supported means of executing or downloading an executable
  
  
• Microsoft System Management Server, which you can use to "push" the distribution of your package from a central location to tens or hundreds of computers at once. Refer to the Microsoft Transaction Server Administrator’s Guide for more information on "pushing" and "pulling" components.
  
  
• Run the client executable as part of your client setup procedure

Note that you must install the client package itself after installing the remote application.