Distributing MTS Packages

You can use the Microsoft Transaction Server Explorer to distribute packages to clients running MTS as well as to clients that are not running MTS. If both the client and server computer are running MTS, you can use the MTS Explorer to create application executables, or push and pull components using the Remote Components folder. If the client computer is not running MTS, use the MTS Explorer to generate application executables that automatically install and configure clients to access remote MTS server applications over distributed COM (DCOM).

On This Page

Working with Remote MTS Computers
Exporting MTS Packages
Generating MTS Executables
Distributing the Client Executable

Working with Remote MTS Computers

If both the server and client computer are running MTS, you can distribute a package by "pulling" and "pushing" components between one or more computers. You can also generate an application executable using the application executable utility in the Microsoft Transaction Server Explorer. See the Generating MTS Executables topic for more information on using the MTS Explorer to generate application executables.

Pushing components means creating remote component entries on remote computers. Once the remote component entries are created, you have to add those component entries to your Remote Components folder on your local machine (pull the components).

The following diagram illustrates how pushing and pulling components configure a remote computer running MTS.

In the diagram, MTS is installed on all three computers. GetReceipt and MoveMoney are both installed in a package on your computer (Server A). When you add the GetReceipt and MoveMoney components to the Remote Components folders of Server B and Server C, two things happen. First, the appropriate DLL files are copied across the network to Server B and Server C. These files will be copied to a subdirectory with the same name as the Package on Server A. This subdirectory will be created under the \<Microsoft Transaction Server Install directory>\Remote directory (for example, C:\Program Files\MTx\Remote\Sample Bank). Second, the Server B and Server C system registries are updated with information from the system registry on Server A.

You can push and pull components only if a shared network directory has been established for storage and delivery of DLLs and type library files. (You can choose any shared directory as long as the component files are contained within one of the folders or subfolders of the shared directory.) The MTS Explorer will automatically locate available shared network directories on servers. On a given server you can have multiple shared directories to access different sets of component files.

In addition, you must ensure that:

• You logged on using a Windows NT account that is a member of the Administrators role of the System Package on the target computer.

• The target computer's System Package identity maps to an NT account that is in the Reader role for your System Package.

• Security is enabled for the System package on both computers. See the Enabling MTS Package Security topic for more information.

To push components, you must first add the appropriate computer or computers to your MTS Explorer and then add your components to the remote computer's Remote Components folder. See the Configuring Your MTS Server topic for information on adding a computer to the Explorer.

Then you must add components to the remote computer's Remote Computer folder.

To add components to the remote computer's Remote Components folder

1. Add the remote computer by selecting the Computers folder and clicking New in the Action menu.

2. Type a name for the computer you want to add, and then click OK. If you do not know the name, you can click the Browse button to select a computer.

3. In the MTS Explorer, open the Remote Components folder of the computer to which you want to add remote components.

4. On the Action menu, click New. You can also right-click and select New and then Component from the right-click menu.

5. In the dialog box that appears, select the remote computer and package that contain the component you want to invoke remotely.

6. From the Available Components list, select the component that you want to invoke remotely, and click the down arrow (Add). This adds the component and the computer on which it resides to the Components to configure on box. If you click the Details checkbox, the Remote Computer, Package, and Path for DLLs are displayed in the Components to configure on box.

7. Click OK.

Note: When you add components that are stored on a remote computer, the required files are stored in the \install directory\remote directory. (The default MTS installation directory is \Program Files\MTS.)

Exporting MTS Packages

Exporting packages allows you to copy a package from one MTS computer to another. For example, you can use the Microsoft Transaction Server Explorer to export a package from a server on which the package was developed to another MTS server for testing.

To export a package:

1. Select the package you want to export in the left pane of the Explorer.

2. On the Action menu, click Export. You can also right-click and select the Export option.

3. In the Export Package dialog box, enter or browse for the package file to create. The component files will be copied to the same directory as the package file.

4. If you want to include any roles that you have identified for the package, click the Save Windows NT user ids associated with roles checkbox.

5. Click Export.

When you export a package, Microsoft Transaction Server creates a package file (with the .pak extension) containing information about the components and roles (if any) included in the original package, and copies the associated component files (dynamic-link libraries (DLL), type libraries, and any proxy/stub DLLs) to the same directory in which the package file was created. Only component DLLs are copied. Package locks against changes or deleting will be exported with the package.

Important: If a component's class ID (CLSID), type library identifier (TypeLibId), or interface identifier (IID) change after you have exported a package, you must export the package again.

Generating MTS Executables

Using the MTS Explorer, you can generate an application executable that installs and configures a client computer to access a remote server application. The client computer that installs the executable must have distributed COM (DCOM) support, but does not require any MTS server files other than the executable to access a remote MTS server application.

The application executable utility is part of the package export feature in the MTS Explorer. This utility allows you to automatically generate application executables that install a client application and configure the client computer to access a server application on a remote MTS servers. Executables generated by the application executable utility by default will configure a client computer to access the deployment server on which the executable was generated.

You can also configure the Remote server name field on the Options tab on the Computer property sheet to point client applications to a server other than the deployment server. If you do not enter the name of another server computer before exporting the package to generate an executable, application executables created on the local computer will automatically configure client computers to access server packages on the local computer.

To configure a client application executable to access a server computer other than the local computer:

1. Select My Computer.

2. Right-click and select Properties from the right-click menu.

3. Select the Options tab and enter the name of the remote server in the Remote server name field in the Replication section.

4. Click OK, and export the package to create the application executable.

The application executable utility automatically creates an executable for the client application.

On the client, the executable automates the following steps:

1. Copies to a temporary directory on the client or server machine and then 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 application to the Remote Applications directory in the \Program Files sub-directory. All remote applications are stored in the Remote Applications directory. Each remote application has an individual directory named by the package globally unique identifier (GUID).

3. Updates the system registry with the entries that either enable clients to use the server application remotely (including information that is related to application, class, programmatic, interface, and library identifiers) or allows the server application to run on the server computer.

4. Registers the application so that a user can use the Add/Remove Programs icon in Control Panel to remove it at a later date. All remote applications are prefaced with "Remote Application" so that you can easily find your application in the list of installed components.

5. Deletes files in the temporary directory generated during installation of the application.

When run on a client computer, the client executable copies the necessary proxy-stub DLLs and type libraries to that computer and updates the client's system registry with information needed by DCOM, including the name of the server computer. Client applications can then access the remote server application.

To create a client executable:

1. Install the server application using the Package Wizard if you have not already done so.

2. Export your package from the server on which your server application is installed to another server. (Note that you must configure the Remote server name property on the Options tab of the Computers property sheet if you would like your clients to access a server other than the deployment server on which you are creating the executable.) Specify a new filename (YourNewFileName) as the package export filename.

3. Locate the folder into which you exported your package. Exporting an existing package in the MTS Explorer generates a "Clients" subdirectory beneath the directory to which you exported the package. The Clients sub-directory contains a single executable with the name specified during package export. When run on any client supporting DCOM, this executable installs all the necessary information for remote clients to access the server application.

Important: Do not run this client executable file on your server computer. Running the client executable on the server computer removes the registry entries required to run the server package. If you make this mistake, you must remove the application using the Add/Remove Programs property sheets in the Control Panel. Then delete and re-install the package using the MTS Explorer.

If another version of a component installed by a client executable already exists on the client machine, the component will only be updated if:

• both versions of the component have version numbers

• the version of the component being installed is later than the version of the component already on the client machine.

You can customize the installation of your client application to include additional files by modifying the clients.ini file in the Clients sub-directory. For example, the clients.ini file can be modified to combine installation of client executables for several different applications, or to include application documentation.

To customize installation:

1. Open the clients.ini file, which is located in the \clients sub-directory.

2. Below the Client Application Files heading, enter the path to the directory in which you want the source code installed on the client computer. For example,

Source Path=c:\program files\mts\test\vb bank

3. Below the ClientApplicationInstallCommands heading, enter the names of the files that you wish to install. Use triple-brackets to enclose the names of the files that you want to install. For example:

1=notepad {{{readme.txt}}} 2={{{vbbank.ex}}}}

4. Below the ClientApplicationSetup heading, indicate if you would like to enable the ExploreApplication setup option by typing "Y" for yes or "N" for no. For example, the following entry would display the application immediately after setup so that the client could create a shortcut to the desktop:

ExploreApplication=Y

After you have customized the clients.ini file, you can use the MTS Explorer to export the server package to create a client executable.

Distributing the Client Executable

The MTS Explorer automates packaging and installing client applications into executables for distribution. Distribute those executables by using one of the following methods:

• Sharing a directory so that clients can copy the executable and run it on their computers.

• Sending an email attachment so that clients can save and run the executable on their computers.

• Incorporating an executable into an HTML script using the <OBJECT> tag. The <OBJECT> tag allows the browser to download the application from a specified object store location to the client machine if the client initiates an event on the HTML page (such as clicking a button). Using the <OBJECT> tag to distribute executables facilitates upgrading executables, since the browser automatically checks the client's registry for the current version of the application. If the existing executable is outdated, the browser downloads the latest version from the object store.

• Using Microsoft System Management Server (SMS) to "push" the distribution of your application from a central location to tens or hundreds of computers at once. Note that you must install the client application itself after installing the application on remote computers.

Removing the Client Executable

Clients can remote the client executable through the Add/Remove option in the Control Panel. Applications installed by MTS executables begin with "Remote Application" in the Install/Uninstall list. To remove the executable, select the appropriate application and click Remove.