NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Microsoft.ComServices

Overview

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.

Deployment and Configuration

Interface IRegistrationHelper

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.

Regsvcs.exe

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:

  1. Loads the assembly
  2. Registers the assembly
  3. Generates a type library
  4. Registers the type library
  5. Installs the type library into the requested application
  6. Configures the components

Possible failures during each corresponding step could be:

  1. If the assembly loading fails, the error message "Failed to load assembly assemblyName.dll" is displayed. It should be followed by an explanation.
  2. If type registration fails, a list of the exception messages that were generated is displayed.
  3. If type library generation fails, a list of exceptions should also be listed. For both steps 2. and 3. the most likely problems will be TypeLoadExceptions, an incorrectly specified ComEmulate attribute on one of the types can be the cause, or referenced assemblies can't be found.
  4. An exception is displayed. This step uses the oleaut LoadTypeLibrary call for registration.
  5. If this step fails, the most likely cause is that the application cannot be found. If the error "One of the objects could not be found" is displayed, first make sure that the type library listed exists and if it does, make sure that the application exists. The most likely problem is that the target application does not exist.
  6. The most likely error in this step could be a mismatched set of properties on one of the components. Most likely it is a SynchronizationAttribute being specified that conflicts with either a default (such as JustInTimeActivation, which is enabled by default), or with a specified transaction. If any transaction setting other than TransactionOption.Ignored is specified, Synchronization must be either Requires or RequiresNew.

Attributes

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);
}

Shared properties

Microsoft.ComServices

Constants

Enum PropertyLockMode
{
    LockSetGet = 0;
    LockMethod = 1;
}
Enum PropertyReleaseMode
{
    Standard = 0;
    Process = 1;
}
enum TransactionVote
{
    int Commit = 0
    int Abort = Commit + 1
}

Microsoft.ComServices.SharedPropertyGroupManager

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

Microsoft.ComServices.SharedPropertyGroup

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.

Microsoft.ComServices.SharedProperty

This is the standard SharedProperty component found in COM+ services.

Properties

Value
Syntax Object Value {get; set;}
Description See COM+ documentation

Shared property usage

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

Contexts

Microsoft.ComServices.ContextUtil

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+

Microsoft.ComServices.IObjectContext

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);
}

Microsoft.ComServices.ITransaction

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);
}

Microsoft.ComServices.BOID

This component serves as the same structure defined in the DTC interfaces.

class BOID extends System.ValueType
{
    int[] rgb;
} 

Microsoft.ComServices.XACTTRANSINFO

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;
}

Contexts usage

ContextUtil.SetAbort();
ContextUtil.DeactivateOnReturn = true;
Object object = ContextUtil.GetNamedProperty(“Session”) 
Isession session = (Isession)object;
session.Timeout = 1000;
session[“someVariableName”] = 4;

Security

Microsoft.ComServices.SecurityCallContext

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+

Microsoft.ComServices.SecurityIdentity

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+

Microsoft.ComServices.SecurityCallers

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.

Security usage

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);
}

Object construction

Microsoft.ComServices.IObjectControl

This is the same interface defined in COM+

Interface IObjectControl
{
    void Activate();
    void Deactivate();
    bool CanBePooled();
}

Microsoft.ComServices.IObjectContruct

This is the same interface defined in COM+

Interface IObjectConstruct
{
    void  Construct(Object constructorObject);
}

Microsoft.ComServices.IObjectContructString

This is the same interface defined in COM+

Interface IObjectConstructString
{
    String ConstructString { get; }
}

Object pooling

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.

Services not yet included