Page #86 (Chapter 12 - IIS Applications and Microsoft Transaction Server)

	Chapter 12 - IIS Applications and Microsoft Transaction Server
	Visual Basic Developers Guide to ASP and IIS
	A. Russell Jones

Copyright 1999 SYBEX Inc.

---

	How Do You Move a Project into MTS?

	The process for moving a project into MTS is involved, but not difficult. The first time you do this, you may find that you have some permissions issues to resolve.

	Make MTS-Specific Code Changes

	The CodeRepositoryMTS project is essentially identical to the non-MTS CodeRepository project except that both the WebClass and the RepositoryData data-access classes run inside MTS. I took these actions to move the classes:

	•		Added the ObjectControl interface to the ADO and RepositoryData classes. Adding the interface is as simple as copying the Activate, Deactivate, and CanBePooled methods into your class and adding a line to implement the interface.

	•		Changed all New keyword ADO object initializations to ObjectContext.CreateInstance calls.

	•		Changed all CRepositoryData object initializations to CreateObject calls.

	•		Set the MTSTransactionMode property for the RepositoryData and ADO classes to RequiresNewTransaction and UsesTransaction, respectively.

	You'll find that you can move classes in and out of MTS easily by wrapping object initialization in a function call:

	Private Function createADO() As ADO

    If Not MTSContext Is Nothing Then

        Set createADO = MTSContext.CreateInstance _

        ("RepositoryData.ADO")

    Else

        Set createADO = New RepositoryData.ADO

    End If

End Function

	Compile the Project

	To debug a project in VB that runs under MTS, you must have the NT 4 Service Pack 4 installed and you must set binary compatibility for the project. That means that you need to compile at least twice. The first time, compile the project normally. Then, right-click the project name in the VB Project Explorer and select Properties. The Project Properties dialog shown in Figure 12.5 appears.

	Check the Unattended Execution and Retained in Memory check boxes, then click the Component tab. You'll see a dialog like the one shown in Figure 12.6.

	Figure 12.6: Component tab on the VB Project Properties dialog

	Select the Binary Compatibility option. Type the path and filename to the copy of the DLL you just compiled, or use the browse button to find the file and select it.

	The term binary compatibility, as applied to a project, is essentially a contract. By checking the Binary Compatibility option, you agree that:

	•		You aren't going to change the interface. That means that you can't add, remove, or rename methods; add arguments; or change return types for any public function. Depending on how well you plan, that's highly restrictive. I recommend that you avoid adding components to MTS until they're complete and fully debugged.

	•		VB will no longer change the class ID as you recompile the project. Usually, VB generates a new class ID each time you compile. A consistent class ID is important for MTS because that's how it manages components. If you install a component in MTS, then recompile the component and change the class ID, the new version of the component will no longer run under MTS.

	If you do need to change the interface and you have already installed the components in MTS, you should remove the components from the MTS package first. To recompile the component, turn binary compatibility off, recompile, then turn binary compatibility back on and reimport the new components into the MTS package.

	Create and Configure an MTS Package

	Launch the MTS Explorer and right-click the Packages Installed entry. Click New Package, then click the Create an Empty Package button (see Figure 12.7).

	Type a name for your package in the dialog that appears, then click Next. MTS will ask you for the name and password of an account under which it should run the package. Select an account with sufficient permissions to run your objects. Click Finish to save your changes.

	The new package appears in the list of installed packages in the MTS Explorer. Expand the Packages Installed entry and find your new package name in the list. Click the plus (+) sign to open it. Right-click Components and select New Component. The Component Wizard dialog in Figure 12.8 appears.

	Click the Install New Component(s) button (don't use the Import Component(s) entry even though your DLLs are already registered). Click the Add Files button and select your DLL, then click the Open button to add the components. MTS adds one entry for each public object in your DLL.

	Note		If you want to delete a component, right-click the component in the MTS Explorer and then select Delete from the pop-up menu.

	By default, MTS creates a Server Package with authorization checking disabled, but you can change these settings at any time. To change the settings, right-click the package name in MTS Explorer and select Properties. I strongly urge you to find other sources for MTS information if you plan to work with it often—there's just not enough room in this book to explain all its capabilities.

	Run the Project

	You're ready to run the project. Based on my experience, you should plan on a significant block of time to get the project running in MTS until you become familiar with the procedures.

	Although you can debug components inside MTS, you should avoid doing so. Debug the components before you add them to MTS. The VB debugging environment simulates a single MTS instance on a single thread, so you will not be able to debug components under load from inside the VB integrated development environment (IDE). To test your project after adding the components, don't run the project; instead, launch your browser and navigate to the URL for the starting WebClass.

	If you make changes to components running in MTS and called by a WebClass, both IIS and MTS can become "confused." To avoid problems, follow this procedure to make component changes:

	1.		Stop the WebClass project.

	2.		Stop IIS by using the Stop button on the WebClass toolbar.

	3.		Use MTS Explorer to shut down the Package containing your components.

	4.		Delete the components from MTS (although this step isn't strictly necessary when you have Binary Compatibility turned on, I've found that MTS doesn't always apply changes properly).

	5.		Alter and recompile the components.

	6.		Add them back into the MTS package.

	7.		Start IIS by using the Start button on the WebClass toolbar.

	8.		Rerun the project.

	To run or debug components that require transactions, the Microsoft Distributed Transaction Coordinator (MSDTC) service must be running. The service, as installed, is set to run manually, not automatically. You can start and stop the service from the MTS Explorer by right-clicking the server name under the Computers entry and selecting Start or Stop MSDTC, but it's more convenient to switch the service to start automatically. To do that, click Start Settings Control Panel, and then double-click Services to launch the Services dialog.

	Select the MSDTC entry from the services list, then click the Startup button to display the Service options dialog (see Figure 12.9). Click the Automatic option, then click OK and Close to close the dialogs. MSDTC will now start automatically when NT starts.

	Change DCOM Permissions

	You may find that you have to add or modify permissions (via the Distributed COM Configuration Manager) for the IUSR_MachineName and IWAM_MachineName accounts before they can launch the Machine Debug Manager or other classes.

	To do that, click Start Run and type dcomcnfg into the Open field. You'll see a list of class IDs (see Figure 12.10). If you scroll down in the list you'll see a list of component names.

	Find the Machine Debug Manager entry in the list and select it. Click the Properties button, then click the Security tab (see Figure 12.11).

	The Machine Debug Manager uses custom access and launch permissions. Click the Edit button for the custom access permissions and add the IUSR_MachineName and IWAM_MachineName accounts to the list with Allow Access permissions (see Figure 12.12).

	Click OK to save the changes. You take almost exactly the same actions to set the launch permissions. Click the Edit button for the custom launch permissions in the DCOM Machine Debug Manager Properties dialog and add both the IUSR_MachineName and IWAM_MachineName accounts to the list with Allow Launch permissions. Click OK to save the changes.

	Permissions issues are the most likely errors you'll encounter as you develop WebClass applications—and they vary from one computer to the next. If you trap all the errors, you'll find that MTS provides reasonably good error entries in the Application event log. For example, Figure 12.13 shows an MTS-generated permissions error.

	All the MTS errors I've encountered have shown the class ID and the account that generated the error. Unfortunately, not all class IDs are associated with a name. When the error doesn't show a class name, you need to work backward through the Registry to debug the problem.

	You can copy the class ID from the error display and search for it in the HKEY_ CLASSES_ROOT key of the Registry to find the associated class name or executable file. Often that alone provides the information you need to solve the problem.