The purpose of the components and interfaces contained in Microsoft.ComServices is to provide access to COM+1.0 services from a managed environment. All methods raise the standard NGWS runtime exceptions for error handling.
This version of the specification is targeted for PDC of the NGWS frameworks and runtime and hence W2K platforms only.
The goal of Microsoft.ComServices for PDC is to enable objects in the managed world to make use of COM+ services and to participate in services with both managed and unmanaged objects.
The first scenario is for two managed objects to participate in a transaction initiated from a managed client. In this case, both managed classes must be implemented as COM components including wrapper classes using the COMEmulate attribute. Further transactional attributes are added to the classes. Then the classes are registered in the COM+ catalog using the tool described in this document.
A further scenario is using one managed object and one COM+ object within one transaction. This can be achieved in a similar way by implementing the managed object as a component and registering the managed component.
Sample code for the first scenario is shown below and the process required to deploy and run the components.
// ----------------------------------------------------------------- // Component.cs // ----------------------------------------------------------------- using System; using System.Runtime.InteropServices; using Microsoft.ComServices; [guid("CE2A4888-82BD-40ad-9BBA-8D129747886F")] [InterfaceTypeAttribute(ComInterfaceType.InterfaceIsIDispatch)] public interface IAccount { void Debit(int amount); } [guid("557B96C4-F7E6-4d48-BBC3-10981E0CA664")] [ComEmulate("Component.Account")] [TransactionAttribute(TransactionOption.Required)] public class EmulAccount { } [guid("871D8D5C-ECC6-40a5-BD82-D5E3B1740095")] internal class Account : IAccount { public void Debit(int amount) { //… do some Db work if (ok) ContextUtil.SetComplete(); else ContextUtil.SetAbort(); } } // ----------------------------------------------------------------- // Client.cs // ----------------------------------------------------------------- using System; using Component; class client { public static int Main() { IAccount accountX = (IAccount)new EmulAccount(); accountX.Debit(100); return 0; } } // ----------------------------------------------------------------- // Compile and run procedure // ----------------------------------------------------------------- sn -k TestKey.snk csc /debug /a.keyfile:Testkey.snk /t:library /r:Microsoft.ComServices.dll /out:Component.dll Component.cs Create a new COM+ application in the COM+ catalog or use an existing name) RegSvcs Component.dll SomeApp al /I:Component.dll csc /I:Component.dll client.cs start client.exe
Note: The ASP intrinsic objects can be obtained within a NGWS object using the named properties available from the NGWS object context when the object was created from ASP. With ASP+ and the NGWS frameworks and runtime, a new set of instrinsic objects are used which is not accessed from a context but rather methods in a namespace, much like the ContextUtil class. The case of legacy COM+ objects created from ASP+ is viable and therefore the instrinsic objects available to legacy COM objects from the COM+ object context may be required so that legacy COM+ object can interact with ASP+. This scenario does not fall into the category of this spec. However, the scenario of managed objects created from ASP would imply that a wrapper would be required to access ASP instrinsics from a managed object. This would typically be a method in the ContextUtil class facilitating the access to these instrinsics. This appears to be an unusual scenario which will not be covered by this spec at this time.
A registration component and interface facilitates the registration of a managed assembly either from a managed or an unmanaged environment. The component is accessed through an interface (IRegistrationHelper) or the class (RegistrationHelper). The interface and class is for internal use only, however, clients can use the command line tool that essentially wraps this private class.
InstallAssembly | |
Syntax | void InstallAssembly(String assemblyName,
String applicationName, String tlbName); |
Description | Leverages the functionality of regAsm, tlbExp, tlbreg and then configures the NGWS application based on attributes in the assembly. |
RegisterAssembly | |
Syntax | void RegisterAssembly(String assemblyName,
String applicationName); |
Description | Leverages the functionality of regAsm, tlbExp and tlbreg. |
ConfigureAssembly | |
Syntax | void ConfigureAssembly(String assemblyName,
String applicationName); |
Description | Configures the NGWS application based on attributes in the assembly. |
UninstallAssembly | |
Syntax | void UninstallAssembly(String assemblyName,
String applicationName); |
Description | Leverages the functionality of regAsm, tlbExp, tlbreg and then unconfigures the NGWS application based on attributes in the assembly. |
The tool uses the InstallAssembly method on the IRegistrationHelper interface. The tlb file name default is the same as the dll name unless explicitly named in the third and optional parameter. Command line help is obtained from Regsvcs /? or Regsvcs /h
regsvcs assemblyName.dll applicationName [tlbName.tlb]
The regsvcs tool goes through the following steps:
Possible failures during each corresponding step could be:
assemblyName
.dll" is displayed. It should be followed by an explanation.The following attributes will be supported in ComServices for PDC.
public enum TransactionMode { Ignored = 0, None = 1, Supported = 1, Required = 2, RequiresNew = 3 } [AttributeUsage(AttributeTargets.Class)] public class TransactionAttribute : Attribute { public TransactionAttribute(); public TransactionAttribute(TransactionMode policy); }
public enum SynchronizationMode { Ignored = 0, None = 1, Supported = 1, Required = 2, RequiresNew = 3 } [AttributeUsage(AttributeTargets.Class)] public class SynchronizationAttribute : Attribute { public SynchronizationAttribute(); public SynchronizationAttribute(SynchronizationMode policy); }
[AttributeUsage(AttributeTargets.Class)] public class JustInTimeActivationAttribute : Attribute { public JustInTimeActivationAttribute(); public JustInTimeActivationAttribute(bool mode); }
[AttributeUsage(AttributeTargets.Class)] public class MustRunInClientContextAttribute : Attribute { public MustRunInClientContextAttribute(); public MustRunInClientContextAttribute(bool mode); }
Constants
Enum PropertyLockMode { LockSetGet = 0; LockMethod = 1; } Enum PropertyReleaseMode { Standard = 0; Process = 1; } enum TransactionVote { int Commit = 0 int Abort = Commit + 1 }
This is the standard SharedPropertyGroupManager component found in COM+ services. New instances are created programmatically.
Methods
SharedPropertyGroupManager | |
Syntax | SharedPropertyGroupManager () |
Description | Creates an instance of a PropertyGroupManager component. |
CreatePropertyGroup | |
Syntax | SharedPropertyGroup CreatePropertyGroup (String name,
PropertyLockMode lockMode, PropertyReleaseMode releaseMode, bool alreadyExists) |
Description | Creates a PropertyGroup component corresponding to the COM+1.0 equivalent. |
Parameters | String name: See COM+ documentation.
PropertyLockMode lockMode: See COM+ documentation. PropertyReleaseMode releaseMode: See COM+ documentation. bool alreadyExists: See COM+ documentation. |
Return values | A SharedPropertyGroup object. |
Group | |
Syntax | SharedPropertyGroup Group(String name) |
Description | Accesses the SharedPropertyGroup object in the collection associated with name. |
Parameters | String name: The name of the shared property group to access. |
Return values | A SharedPropertyGroup object indexed by name. |
GetEnumerator | |
Syntax | IEnumerator GetEnumerator() |
Description | Retrieves the enumerator for accessesing the SharedPropertyGroupManager collection. |
Return values | An IEnumerator interface |
This is the standard SharedPropertyGroup component found in COM+ services. Instances of this component are not directly created but obtained from a call to SharedPropertyGroupManager.CreatePropertyGroup.
Methods
CreateProperty | |
Syntax | SharedProperty CreateProperty (String name, bool alreadyExists) |
Description | Creates a SharedProperty component corresponding to the COM+1.0 equivalent. |
Parameters | String name: See COM+ documentation.
bool alreadyExists: See COM+ documentation. |
Return values | A SharedProperty object for the newly created or existing property. |
CreatePropertyByPosition | |
Syntax | SharedProperty CreatePropertyByPosition (int index, bool alreadyExists) |
Description | Creates a SharedProperty component corresponding to the COM+1.0 equivalent. |
Parameters | Int index: See COM+ documentation.
bool alreadyExists: See COM+ documentation. |
Return values | A SharedProperty object for the newly created property. |
PropertyByPosition | |
Syntax | SharedProperty PropertyByPosition (int index) |
Description | See COM+ documentation. |
Property | |
Syntax | SharedProperty Property (String name) |
Description | See COM+ documentation. |
This is the standard SharedProperty component found in COM+ services.
Properties
Value | |
Syntax | Object Value {get; set;} |
Description | See COM+ documentation |
SharedPropertyGroupManager spgm = new SharedPropertyGroupManager(); SharedPropertyGroup groupEarl = spgm.CreatePropertyGroup(“Earl”, PropertyLockMode.LockSetGet, PropertyReleaseMode.Standard, alreadyExisits); spgm.Group(“earl”).Item(“salary”).Value = 100000000; groupEarl.PropertyByPosition(1).Value = 100000000; for each SharedPropertyGroup group in spgm group.Property(“salary”).Value = 1000 next group
This component provides access to COM+ context objects. New instances are not created programmatically.
Methods
SetComplete | |
Syntax | static void SetComplete () |
Description | Calls SetCompete on IObjectContext for the calling thread. |
SetAbort | |
Syntax | static void SetAbort () |
Description | Calls SetAbort on IObjectContext for the calling thread. |
EnableCommit | |
Syntax | static void EnableCommit() |
Description | Uses the COM+ call on IObjectContext for the calling thread. |
DisableCommit | |
Syntax | static void DisableCommit() |
Description | Uses the COM+ call on IObjectContext for the calling thread. |
GetNamedProperty | |
Syntax | static Object GetNamedProperty(String name) |
Description | Accesses additional context properties specific to ASP, Application, Session, Request, Response and Server objects. |
Properties
DeactivateOnReturn | |
Syntax | static void DeactivateOnReturn {get; set} |
Description | Calls SetDeactivateOnReturn and GetDeactivateOnReturn on IContextState in COM+ |
MyTransactionVote | |
Syntax | static void MyTransactionVote {get; set;} |
Description | Calls SetMyTransactionVote and GetMyTransactionVote on IContextState in COM+ |
ObjectContext | |
Syntax | static IObjectContext ObjectContext {get;} |
Description | Retrieves the IObjectContext interface pointer for the current context |
Transaction | |
Syntax | static Object Transaction {get;} |
Description | Calls GetTransaction on IObjectContextInfo in COM+. |
Return values | The returned object supports the ITransaction interface detailed below |
IsInTransaction | |
Syntax | static bool IsInTransaction {get;} |
Description | Calls IsInTransaction on IObjectContextInfo in COM+ |
IsTransactionDoomed | |
Syntax | static bool IsTransactionDoomed {get} |
Description | Provides information about the current transaction’s status |
TransactionId | |
Syntax | static GUID TransactionId {get;} |
Description | Calls GetTransactionId on IObjectContextInfo in COM+ |
ContextId | |
Syntax | static GUID ContextId {get;}; |
Description | Calls GetContextId on IObjectContextInfo in COM+ |
ActivityId | |
Syntax | static GUID ActivityId {get;} |
Description | Calls GetActivityId on IObjectContextActivity in COM+ |
This is the same interface defined in COM+
Inteface IObjectContext { Object CreateInstance(Guid rclsid, Guid riid); void SetComplete(); void SetAbort(); void EnableCommit(); void DisableCommit(); bool IsInTransaction(); bool IsSecurityEnabled(); bool IsCallerInRole(String role); }
This is the same interface defined in the DTC interfaces. This interface is implemented by the object returned in ContextUtil.Transaction.
Interface ITransaction { void Commit(int retaining, int grfTC, int grfRM); void Abort(BOID reason, int retaining, int async); void GetTransactionInfo(out XACTTRANSINFO info); }
This component serves as the same structure defined in the DTC interfaces.
class BOID extends System.ValueType { int[] rgb; }
This component serves as the same structure defined in the DTC interfaces.
class XACTTRANSINFO extends System.ValueType { BOID unitOfWork; int isolationLevel; int isolationFlags; int grfTCSupported; int grfRMSupported; int grfTCSupportedRetaining; int grfRMSupportedRetaining; }
ContextUtil.SetAbort(); ContextUtil.DeactivateOnReturn = true; Object object = ContextUtil.GetNamedProperty(“Session”) Isession session = (Isession)object; session.Timeout = 1000; session[“someVariableName”] = 4;
This component provides access to COM+ security call context and is similar but not identical to the SecurityCallContext object in Visual Basic. New instances are not created programmatically but obtained through the CurrentCall method.
Methods
IsCallerInRole | |
Syntax | bool IsCallerInRole(String role) |
Description | Calls IsCallerInRole on ISecurityCallContext. |
Parameters | String role: See COM+ documentation. |
Return values | See COM+ documentation. |
IsUserInRole | |
Syntax | bool IsUserInRole(String user, String role) |
Description | Calls IsUserInRole on ISecurityCallContext. |
Parameters | Object user: See COM+ documentation.
String role: See COM+ documentation. |
Return values | See COM+ documentation. |
Properties
CurrentCall | |
Syntax | static SecurityCallContext CurrentCall {get;} |
Description | Returns a reference to a SecurityCallContext object associated with the current call. |
SecurityEnabled | |
Syntax | bool SecurityEnabled {get;} |
Description | Calls IsSecurityEnabled on ISecurityCallContext. |
DirectCaller | |
Syntax | SecurityIdentity DirectCaller {get;} |
Description | Retrieves the DirectCaller item from the ISecurityCallContext collection in COM+ and returns the item as a SecurityIdentity object. |
OriginalCaller | |
Syntax | SecurityIdentity OriginalCaller {get;} |
Description | Retrieves the OriginalCaller item from the ISecurityCallContext collection in COM+ and returns the item as a SecurityIdentity object. |
Callers | |
Syntax | SecurityCallers Callers {get;} |
Description | Retrieves the Callers item from the ISecurityCallContext collection in COM+ and returns the item as a SecurityCallers object. |
NumCallers | |
Syntax | int NumCallers {get;} |
Description | Retrieves the NumCallers item from the ISecurityCallContext collection in COM+ |
MinAuthenticationLevel | |
Syntax | int MinAuthenticationLevel {get;} |
Description | Retrieves the MinAuthenticationLevel item from the ISecurityCallContext collection in COM+ |
This component accesses ISecurityIdentityColl in COM+ and provides the items in the ISecurityIdentityColl collection as properties. New instances are not created programmatically but obtained from components SecurityCallContext and SecurityCallers.
Properties
SID | |
Syntax | Object SID {get;} |
Description | Retrieves the SID item from ISecurityIdentityColl in COM+ |
AccountName | |
Syntax | String AccountName {get;} |
Description | Retrieves the AccountName item from ISecurityIdentityColl in COM+ |
AuthenticationService | |
Syntax | Int AuthenticationService {get;} |
Description | Retrieves the AuthenticationService item from ISecurityIdentityColl in COM+ |
ImpersonationLevel | |
Syntax | Int ImpersonationLevel {get;} |
Description | Retrieves the ImpersonationLevel item from ISecurityIdentityColl in COM+ |
AuthenticationLevel | |
Syntax | Int AuthenticationLevel {get;} |
Description | Retrieves the AuthenticationLevel item from ISecurityIdentityColl in COM+ |
This component accesses ISecurityCallersColl in COM+ and provides the items in the ISecurityCallersColl collection as indexed properties. New instances are not created programmatically but obtained from the SecurityCallContext component. The component also implements the IEnumerable interface.
Methods
GetEnumerator | |
Syntax | IEnumerator GetEnumerator() |
Description | Retrieves the enumerator for the ISecurityCallersColl collection |
Properties
Count | |
Syntax | Int Count {get;} |
Description | The number of indexed SecurityIdentity objects |
this | |
Syntax | SecurityIdentity this[int index] |
Description | An indexed property used to retrieve a specified item in the security callers collection. |
SecurityCallContext call = SecurityCallContext.CurrentCall; foreach (SecurityIdentity id in call.Callers) { Console.WriteLine("Caller: " + id.AccountName); } SecurityCallers callers = SecurityCallContext.CurrentCall.Callers; For (int i = 0; i < callers.Count; i++) { Console.WriteLine("Caller: " + callers[i].AccountName); }
This is the same interface defined in COM+
Interface IObjectControl { void Activate(); void Deactivate(); bool CanBePooled(); }
This is the same interface defined in COM+
Interface IObjectConstruct { void Construct(Object constructorObject); }
This is the same interface defined in COM+
Interface IObjectConstructString { String ConstructString { get; } }
Object pooling is supported on legacy COM+ components called from a managed environment and on registered managed components with the ComEmulate attribute. Simply set the object pooling properties in the COM+ catalog by script, code or the component services explorer.