Creating MTS Objects

[This product will work only on Windows NT 4.0 versions and earlier. For Windows 2000 and later, see COM+ (Component Services).]

You can create MTS objects by:

• Using context objects.
• Using transaction context objects.
• Using standard COM functions like CoCreateInstance or CreateObject.

Note If you are using Visual C++ and running an MTS component in-process, you must:

• Call CoInitialize(NULL) before requesting services from MTS or creating an MTS object.
• Call CoInitializeSecurity to initialize process-specific security. MTS security is disabled when loading an MTS object in-process.
• Call CoUninitialize only after you have finished using MTS or MTS objects, preferably just prior to terminating your application. You cannot call CoInitialize again and invoke more MTS services. Once CoUninitialize has been called, your application no longer executes in the MTS run-time environment.

Creating Objects Using a Context Object

You can create an MTS object by calling the CreateInstance method on the IObjectContext interface of an object's context object. The new MTS object's context inherits the activity, possibly a transaction, and all security identities from the creating object's context.

Creating an object using a context object

Do Not Create Non-MTS Local Servers Using CreateInstance

Creating non-MTS local servers using the context object's CreateInstance method is strongly discouraged. Such servers will not scale well and may result in additional server instances that are not shut down by MTS. If you need to create a non-MTS local server, use CoCreateInstance.

Do not use COM surrogates within MTS. Instead, load in-process servers into MTS server processes.

Creating Objects Using a Transaction Context Object

If you want your base client to control transaction boundaries, use a transaction context object. You can create an MTS object by calling the CreateInstance method of the ITransactionContext interface. The new MTS object's context inherits the activity, possibly a transaction, and the identity of the initial client from the transaction context object. You can call the Commit method to commit an object's work and the Abort method to abort its work.

Creating an object using a transaction context object

Creating Objects Using CoCreateInstance

You can create MTS objects by using CoCreateInstance or any equivalent method based on CoGetClassObject and IClassFactory::CreateInstance. While this approach should suffice for many base client applications, there are some significant limitations for the client, including the inability to control transaction boundaries. Base clients that need this additional level of control can use a transaction context object.

Instantiating an object with CoCreateInstance

When you use CoGetClassObject with a component that is registered to run under MTS, it returns a reference to an MTS-provided class factory. This allows MTS to participate in the client's calls to IClassFactory::CreateInstance. The MTS class factory creates the context object and then calls the component's real class factory.

For clustered servers, if you are using the CoCreateInstanceEx function, use the name of the virtual server containing the MSDTC resource in the pwszName field of the COSERVERINFO structure. (See the Microsoft Platform SDK documentation for more details about CoCreateInstanceEx.)

Important It is recommended that you do not call CoCreateInstance to create MTS objects from within MTS objects. When you do so, the new object's context cannot inherit any properties from its client's context. In particular, the new object cannot execute within the scope of its client's transaction.

Aggregation

You cannot use an MTS object as part of an aggregate of other objects. CoCreateInstance returns CLASS_E_NOAGGREGATION to indicate an attempt to create an MTS object with another controlling IUnknown.

You can, however, create an MTS object that is implemented as an aggregation of objects.

Creating Objects Using Visual Basic

You can use the following object creation methods in Microsoft® Visual Basic® to create MTS objects:

• The CreateObject function
• The GetObject function
• The New keyword (see the Important note for limitations)
• Automatically if the object is an Application object

Using Visual Basic object creation methods results in the same limitations as using CoCreateInstance. To inherit a transaction from the creating object's context, use CreateInstance.

Important Do not use the New operator, or a variable declared As New, to create an instance of a class that is part of the active project. In this situation, Visual Basic uses an implementation of object creation that does not use COM. To prevent this occurrence, it is recommended that you mark all objects passed out from a Visual Basic componentas Public Creatable, or its equivalent, and created with either the CreateObject function or the CreateInstance method of the ObjectContext object.

See Also

MTS Objects, Calling MTS Components, Context Objects, Passing Object References, Deactivating Objects, CreateInstance