Creating MTS Packages

Creating packages is the final step in the MTS application development process. Package design decisions dictate the organization and properties of components. Although creating MTS packages does not require programming knowledge, you should be thoroughly familiar with the design and implementation specifications of the application.

It is highly recommended that you review this section of the MTS Administrator's Guide in conjunction with the MTS Programmer's Guide so that you understand the design-time implications for packaging components using the Microsoft Transaction Server Explorer.

Packaging components enacts development decisions that include resource pooling, activation settings, and support for transactions. For example, when you create a package, you should try to group components that share resources in the same package. Consider the type of resources that components are sharing in your package, and group components that share "expensive" resources, like connections to a specific database.

Packaging components to take advantage of resource pooling results in more efficient MTS applications. If you review the MTS Programmer's Guide in conjunction with the MTS Administrative Guide, you can learn more about the development concerns that motivate creating and populating packages using the Explorer. See the Installing MTS Development Samples and Documentation topic for instructions on obtaining the MTS Programmer's Guide.

On This Page

Creating an Empty MTS Package
Adding a Component to an MTS Package
Importing an MTS Component into a Package
Removing an MTS Component from a Package
Building an MTS Package for Export
Setting MTS Package Properties
Refreshing Component Settings
Setting MTS Activation Properties
Setting MTS Transaction Properties
Setting MTS Authentication Levels
Locking Your MTS Package

Creating an Empty MTS Package

The first step in using the MTS Explorer is to create a package. A package, which can easily be created in the MTS Explorer, is a collection of components that run in the same process. You can either create an empty package and then add components, or you can install a pre-built package. Add packages by using the Package wizard or by dragging a package file (.pak) from the Windows NT® Explorer and dropping it into the right pane of the MTS Explorer.

Packages define the boundaries for a server process running on a server computer. For example, if you group a sales component and a purchasing component in two different packages, these two components will run in separate processes with process isolation. Therefore, if one of the server processes terminates unexpectedly (such as an application fatal error), the other package can continue to execute in its separate process.

To create an empty package

1. In the left pane of MTS Explorer, select the computer for which you want to create a package.

2. Open the Packages Installed folder for that computer.

3. On the Action menu, click New. You can also select the Package Installed folder and either right-click and select New and then Package from the right-click menu, or select the Create a new object button on the MTS toolbar.

4. Use the Package wizard to install either a pre-built package or create an empty package. If you create an empty package, you must add components and roles before it will be functional.

5. Click the Create an empty package button.

6. Type a name for the new package, and click Next.

7. Specify the package identity in the Set Package Identity dialog box, and then click the Finish button.

The default selection for package identity is Interactive User. The interactive user is the user that logged on to the server computer on which the package is running. You can select a different user by selecting the This user option and entering a specific Windows NT user.

Adding a Component to an MTS Package

An MTS component is a reusable piece of code and data that is built to the Component Object Model (COM) specification. Components enact business logic in an application.

You can add a component to a package by:

• using the component wizard

• moving a component from an existing package

To add components to the Components folder of a package, you can either use the component wizard in MTS Explorer or you can drag dynamic-link libraries (DLL) that contain the components you want from Windows NT Explorer and drop them in the package . If you use the Component wizard, you can either install a new component, which adds the component to the system registry, or import components that have already been registered. Components can be added to empty packages or existing packages.

To move a component from an existing package, simply drag and drop the component from the existing package to the new component.

Note that a single MTS application can contain components that can be installed in multiple packages. You can place different components that are housed in the same DLL into completely separate packages.

To add a component to a package

1. In the left pane of MTS Explorer, select the computer on which you want to install the component.

2. Open the Packages Installed folder, and select the package in which you want to install the component.

3. Open the Components folder.

4. On the Action menu, click New. You can also select the Components folder, right-click, and select New and then Component from the right-click menu, or select the Create a new object button on the MTS toolbar.

5. Click the Install new component(s) button.

6. In the dialog box that appears, click Add Files to select the files you want to install. You should select the DLL that contains the component you want to install. If the component has an external type library or proxy/stub DLL, also add those files. Make sure that in your Windows NT Explorer, the Hidden files option is set to Show all files. If this option is set to hide files with the .dll file name extension, you will not see the DLLs that contain your component in the Component wizard Add Files dialog box. You will have to restart the MTS Explorer if you change this setting.

7. In the dialog box that appears, select the file or files you want to add, and click Open. You can display all available files, just DLLs, or just type libraries by clicking the appropriate option in the Files of type box.

8. After you add the files, the Install Components dialog box displays the files you have added and their associated components. If you select the Details check box, you will see more information about file contents and the components that were found. Microsoft Transaction Server components must have a type library. If MTS cannot find your component's type library, your component will not appear in the list. You can also remove a file from the Files to install list by selecting it and clicking Remove Files.

9. Click the Finish button to install the component. It is important to note that installing a component allows you to view the interfaces and methods on that component. When you import a component, the imported component's interfaces and methods are not visible in MTS Explorer.

Importing an MTS Component into a Package

You can use the Microsoft Transaction Server Explorer to import into packages specific components that have already been registered on your computer as COM (Component Object Model) components. Importing a component does not install the interface or method information required to set interface properties or to configure access to the component from a remote client. If possible, install rather than import components.

To import a component into a package

1. In the left pane of MTS Explorer, select the computer on which you want to import the component.

2. Open the Packages Installed folder, and select the package into which you want to import the component.

3. Open the Components folder.

4. On the Action menu, click New. You can also select the Components folder and either right-click and select New and then Component from the right-click menu, or select the Create a new object button on the MTS toolbar.

5. Click the Import component(s) that are already registered button.

6. Select the components you want to import.

7. Click Finish.

Removing an MTS Component from a Package

You can use Microsoft Transaction Server Explorer to remove components from a package. The impact of deleting a component depends on how the component was added to the MTS run-time environment. If you installed the component, deleting the component completely removes registry information from both the MTS run-time environment and your computer. If you imported the component, the component will be removed from the MTS run-time environment, but will remain registered on the deployment computer as a COM (Component Object Model) component. You must then manually remove the COM component registry entries and component files from your deployment computer.

To remove a component from a package

1. In the right pane of the Explorer, select the package that contains the component you want to remove.

2. Open the Components folder.

3. Select the component you want to remove.

4. On the Action menu, click Delete. You can also select the component and either right-click and select Delete from the right-click menu, or select the Delete button on the MTS toolbar.

5. Click Yes in the dialog box that appears.

Building an MTS Package for Export

To export packages, your components must be properly configured so that MTS can automate package registration on a server or client computer. When building a package, therefore, you should consider how the package might be distributed.

You can use the package export option in the Microsoft Transaction Server Explorer to export your package to another server computer running MTS. You can also generate application executables for remote client computers running Windows NT or Windows 95 (with DCOM support) to access your server application. Consider the requirements for package export while you are creating and configuring packages.

By default, application executables configure client machines to access the remote MTS server on which the executable was generated. You can modify the location of the server application by configuring the Option tab of the Computer property sheets. Before you generate the executable, select My Computer in the MTS Explorer, right-click, and choose Properties from the right-click menu. Click the Options tab and enter the machine name of the server that you want the client computer to access in the Remote server name box. Note that the machine name that you enter must be the MTS server running the package. Then click OK. When you generate the client executable, the executable will configure that client to access the server that you specified in the Remote server name box. This allows you to statically load balance your application by having multiple clients point to more than one machine running the same package.

Requirements for Package Export

Package developers, or advanced system or Web administrators who deploy packages must observe the following requirements while building and deploying MTS packages:

• Remove the descriptions of standard COM interfaces from the client-only application type libraries. For example, the package developer may have defined an interface such as IObjectSaftey in a type library in order to use that interface with Visual Basic. Removing descriptions of the interface before exporting will prevent the interface from being improperly registered and unregistered on client machines. Failure to remove standard COM interface descriptions from the client-only type library could lead to the failure of any other application using those standard interfaces.

• If any of the globally unique identifiers (GUIDs) that are in the server package (including class, interface, or type-library identifiers) and are used by clients change, you will need to re-export the package if you want to generate an updated client install executable. Clients of your application will not be able to access the server application 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.

For more information about using the MTS Explorer to distribute MTS packages, see the Distributing MTS Packages section.

Setting MTS Package Properties

Package properties determine package configuration. To access these property sheets, right-click the package in the Microsoft Transaction Server Explorer, or select the package and choose the Properties option from the Action menu.

There are five package property sheets:

• General

  Displays the name and description the computer.

• Security

  Enables authorization checking. The default security setting does not enable authorization checking. See the Enabling MTS Package Security topic for more information.

• Advanced

  Determines whether the server process associated with a package always runs, or whether it shuts down after a certain period of time.

• Identity

  Used to set which user is allowed to access a package. The default value is Interactive User, which is the user that is currently logged on to the Windows NT server account. If you want to select another user, you can select the This user option and specify an account name and password.

• Activation

  Used to set the activation level for the package and its components. You can either set the activation level to Library Package so components are activated in the creator's process, or to Server Package so that the package runs in a dedicated server process.

  See the Setting MTS Activation Properties topic for more information.

To modify package or component properties, you must use property sheets.

To access property sheets:

1. Right-click the package or component that you would like to configure and choose Properties. You can also select the item, open the Action Menu, and select Properties.

2. Select the tab of the sheet that you will use.

3. Update the property setting.

4. Click OK to save the setting and return to the Explorer.

Refreshing Component Settings

It is important to refresh the MTS settings for components each time you recompile your project. Refreshing component settings prevents your component registry settings from being rewritten.

To refresh your component settings

1. In the left pane of the MTS Explorer, select the computer that contains the components you would like to refresh.

2. On the Action menu, click Refresh All Components. This updates Transaction Server with any changes to the system registry, component CLSIDs, or interface identifiers (IIDs). You can also refresh components by selecting the computer in the left pane of the Explorer and clicking the Refresh button on the MTS toolbar.

   The Refresh All Components command works if any item below a computer in the MTS Explorer hierarchy has been selected. The command will apply to the selected computer.

Setting MTS Activation Properties

Activation properties should be determined at package design time. You can select a package to run in process of the client that called it (as a library package) or in a dedicated server process (as a server package).

Library Package

Select this option to run the package as a library package. A library package runs in the process of the client that creates it. This option is only available for clients on the computer on which the package is being installed and configured. Note that library packages offer no component tracking, role checking, or process isolation.

Server Package

Select this option to run this package as a server package. A server package runs in its own process on the local computer. Server packages support role-based security, resource sharing, process isolation, and process management (such as package tracking).

To set the package activation property

1. Select the package you want to configure.

2. On the Action menu, click Properties, and select the Activation tab. You can also access the property sheets by selecting the item and either right-clicking and choosing Properties, or clicking the Properties button on the MTS toolbar.

3. Click the Activation tab and specify the appropriate activation property.

4. Click OK to return to the Explorer.

Setting MTS Transaction Properties

You should determine if you want your application to support transaction at design time, and then use the Microsoft Transaction Server Explorer during deployment to set the component transaction property. The Transaction tab on the property sheet determines how a component supports transactions. You can select one of the following settings for component transaction properties:

• Requires a transaction This indicates that the component's objects must execute within the scope of a transaction. When a new object is created, its object context inherits the transaction from the context of the client. If the client doesn't have a transaction, MTS automatically creates a new transaction for the object.

• Requires a new transaction This indicates that the component's objects must execute within their own transactions. When a new object is created, Transaction Server automatically creates a new transaction for the object, regardless of whether its client has a transaction.

• Supports transactions This indicates that the component's objects can execute within the scope of their client's transactions. When a new object is created, its object context inherits the transaction from the context of the client. If the client doesn't have a transaction, the new context is also created without one.

• Does not support transactions This indicates that the component's objects shouldn't run within the scope of transactions. When a new object is created, its object context is created without a transaction, regardless of whether the client has a transaction.

Whenever an instance of a component is created, MTS checks the component's transaction attribute to determine whether the instance should run in a transaction.

Not all components are designed to support transaction processing. If your component is not designed to use transaction processing, make sure that the transaction attribute on the component's Transaction tab is set to Does not support transactions.

Note that you cannot modify transaction attributes if components in the package have been locked. For more details, see Locking Your Package.

To set component transaction properties

1. Select the component you want to configure.

2. On the Action menu, click Properties, and select the Transaction tab. You can also access the property sheets by selecting the item and either right-clicking and choosing Properties, or clicking the Properties button on the MTS toolbar.

3. Click the appropriate transaction attribute box.

4. Click OK.

For an overview of distributed transactions and instructions on how to monitor and manage transactions, see the Managing MTS Transactions.

Setting MTS Authentication Levels

An application's authentication level indicates the level of security used to authenticate client requests. If authentication is not required for clients of an application, select the Anonymous option on the Security tab of the Package property sheet. If you want to require authentication of clients, use the Impersonate setting. The server process will set the authentication level to that specified level and the impersonation level to impersonate so it is not affected by distributed COM (DCOM).

Unless you have a thorough understanding of DCOM authentication levels, it is recommended that you leave your package authentication setting at the MTS default setting, which is Packet level.

The following table describes the different DCOM authentication settings:

To set authentication levels for a computer

1. In the MTS Explorer, select the package you want to configure.

2. In the Action menu, click Properties, and select the Security tab. You can also access the property sheets by selecting the package and either right-clicking and choosing Properties, or clicking the Properties button on the MTS toolbar.

3. Select the level of authentication you want to configure for this package under Authentication level for calls.

4. Click OK.

Locking Your MTS Package

After you have developed, installed, or deployed your application, consider locking your package so component configuration cannot be modified. You can lock your package before exporting a server application to another MTS computer that is maintained by a system or Web administrator, or before you distribute a server application to customers.

You can lock your package against:

• Changes

  This setting ensures that administrators cannot modify package configuration without disabling the lock.

• Deletions

  This setting ensures that administrators cannot delete a package without disabling the lock.

To lock your package

1. Once you have finished configuring your package, select the Advanced tab in the package property sheets.

2. In the Permissions section of the Advanced property sheet, select either the Disable deletion option (which prohibits users from deleting the package) or the Disable changes option (which blocks users from making any changes to the package properties.

You can unlock a package by clearing the Advanced property sheet check-boxes.