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!

System.Runtime.Remoting Namespace

Classes

Class Description
ChannelServices  
ConstructionCall [To be supplied.]
ConstructionResponse [To be supplied.]
Context Key Points:

A boundary containing a collection of objects with the same usage rules

Context rules include: synchronization, thread affinity, transactions, etc.

Classes are marked with ContextAttribute, which provide the usage rules

Execution system:

On the newobj IL instruction, the EE finds a compatible or creates a new Context for the object

Ensures the rules are enforced when entering and leaving a context

Provides synchronization rules for managed objects

Flexible synchronization model

A context is an ordered sequence of properties that define an environment for the objects resident inside it. Contexts get created during the activation process for objects that are configured to require certain automatic services such synchronization, transactions, just-in-time activation, security etc. Multiple objects can live inside a context.

Below is a brief summary of some of the Context characteristics:

Contexts are a general mechanism that bound a set of objects.

A context is composed from a set of Context properties.

Classes that can be bound to a context are called context-bound classes.

Context-bound objects are referenced directly within their own context and via a proxy when referenced from another context.

Any call from an object in one context to an object in another context will go through a context proxy and be affected by the policy that the combined context properties enforce.

Contexts are created during object activation i.e. a new object is either placed in an existing context or a new one is created for it, but once there, the object stays in its context for life.

A new object's context is generally chosen based on meta-data attributes on the class. This mechanism is extensible via custom attributes. These are known as static context properties, which are compiled into the class meta-data. Dynamic (also known as configuration) context properties can be applied and configured by administrators.

As a general rule, contexts are freed when there are no longer any external references to objects in the context and there are no threads executing in the context.

When context-bound objects access "agile" locations (location accessible from anywhere- like class static variables) that contain context-bound objects, proxy wrapping and unwrapping must be done.

There is one special kind of context property called an AppDomain property. An AppDomain property defines the boundary that contains the set of statics for a program (set of classes). If the same class is loaded into two contexts with different AppDomain properties then two copies of all of its static member variables are created.

Because all context-bound objects can be proxied across contexts, this imposes certain restrictions on how code can manipulate context-bound objects. For example, code cannot access a field on a context-bound object directly. Another example is that non-virtual calls must be made through an indirection and no inlining is allowed (to allow proxies when appropriate). This makes context-bound objects a good bit more expensive than one would like.

Classes, which are not context-bound, are sometimes referred to as agile classes. This should not be confused with agile locations (described below in the location section), although the ideas are parallel. Agile objects are not bound to contexts and they are not proxied across contexts within the same AppDomain. Agile objects are only agile within an AppDomain. Agile objects "live" in the DefaultContext (of which there is one per app-domain). The default context has no non-trivial properties. Any object passes across an AppDomain boundary is considered to be remoted.

Context-bound objects are very appropriate for transaction isolation/ propagation and other features where the cost is acceptable.

ContextAttribute ContextAttribute is the root for all context attributes. ContextAttribute provides the default implementations of IContextAttribute and IContextProperty. Simple Context properties can derived from ContextAttribute with the context attribute and the context property being in the class. For more specialized or more sophisticated needs the context attribute still derives from ContextAttribute and context property can be split into a separated class.
ContextProperty  
Embedded [To be supplied.]
Header Defines the out-of-band data for a call.
Lease  
LeaseManager The LeaseManager is responsible for managing and maintaining a list of registered leases and notifying the relevant sponsors of any changes in the state of the lease.
LeaseSink ????????????????????????????????????????
LifetimeServices  
MethodCall [To be supplied.]
MethodResponse [To be supplied.]
ObjectHandle [To be supplied.]
ObjRef Defines the marshaled object reference class.

An ObjRef is a serializable representation of an object used to transfer an object reference across an AppDomain boundary. The act of creating an ObjRef for an object is called marshaling. The ObjRef can be transferred via a channel into another AppDomain (possibly on another process or machine). Once in the other AppDomain, the ObjRef must be parsed to create a Proxy for the Object, generally connected to the real Object. This operation is called unmarshaling. ObjRefs have enough information that describes the Type/ class of the object being marshaled (like the class hierarchy), something that will uniquely identify the specific object instance (the URI) and how to reach the remoting-subdivision where the object lives (communication related information).

An important notion to be aware of about marshaling are the semantics of Marshal-by-Value versus Marshal-by-Reference. When a reference to an Object is converted to an ObjRef such that the Proxy created after unmarshaling talks to the original object for most method calls via a proxy, this is called Marshal-by-Reference. However, there are objects whose state does not change in any interesting way once initialized. For such objects, it makes sense to send over the entire state of the Object in the ObjRef and then create a local object that is a clone of the remote one within the remoting-boundary of the client. This is called Marshal-by-Value.

OneWayAttribute [To be supplied.]
RealProxy  
RemotingException This class is the exception class for remoting. An Exception is thrown when something has gone wrong during remoting.
RemotingServices  
RemotingSurrogateSelector [To be supplied.]
ReturnMessage This class implements IMethodReturnMessage which is used to return a message in response to a method call on an object at the end of the message sink.
SchemaType [To be supplied.]
Synchronization [To be supplied.]
ThreadAffinity Key Points:

Refinement of Synchronized Context

Mark type with Thread Affinity Context Attribute

Only a single thread allowed to execute within the Synchronization Domain, hence only that thread can access instance fields and methods

Useful:

User Interface objects

Objects that hold onto OS resource that should only be accessed on the thread that created them

The Thread Affinity Context Property provides a similar capability as the Synchronization Context property with the further constraint that only a single thread is allow to execute within the context or synchronization domain at any time. This is useful for objects that could hold onto OS resources that should only be accessed from a particular thread and only that thread. Thread Affinity is useful when users want to always access the object on the same thread. Certain UI resources should only be accessed on the same thread, on which they were created.

An instance of this property in a context enforces a thread affinity domain for the context (and all contexts that share the same instance). This means that for all contexts sharing an instance of this property, all methods on objects resident in those contexts will execute on the same thread for the lifetime of the objects.

This is done by contributing message sinks that intercept and serialize in-coming calls.

If the property is marked for reentrancy, then call-outs are intercepted too. The call-out interception allows other waiting calls to enter the thread affinity domain.

[ThreadAffinity()]

public class Foo: ContextBoundObject

{

. . .// implementation for Foo

}

// Make an instance of Foo

void SomeOtherMethod(void)

{

. . . Foo foo = new Foo();

}

TrackingServices  
URLAttribute [To be supplied.]
XmlNamespaceEncoder [To be supplied.]

Interfaces

Interface Description
IActivator  
IChannel Channels provide conducts for messages that cross remoting boundaries (for example, Context, AppDomain, Processes, and Machines). These crossings include both inbound and outbound. A channel can listen on an endpoint for inbound messages or send to an endpoint for outbound messages or both. This provides an extensibility point in the runtime to plug in a wide range protocols, even though the runtime may not be at the other end of the channel.

Runtime objects can be used to expose and represent a wide and rich set of semantics and entities. The channel provides the extensibility point to convert the messages to and from the specific protocols. If there are runtimes are both ends of the channel, a "virtual channel" is created between the two ends, in order to connect the client and sever sink chains on either side of the boundary together.

The client part of the channel is located at the end of Client context sink chain. The server part of the channel is located at the start of the Server context sink chain. Messages are delivered to the client channel via the IMessageSink interface, travel through the channel, and are received by the server channel. The server channel delivers the message to the first server context sink. Channels must expose the IChannel interface, which provides informational properties such as the ChannelName, ChannelPriority and MimeType. Channels are registered via RegisterChannel.

IChannelInfo Provides custom channel information that is carried along with the ObjRef.
IChannelReceiver  
IChannelSender The sending side of channels must expose the IChannelSender interface.
IConstructionCallMessage [To be supplied.]
IConstructionReturnMessage [To be supplied.]
IContextAttribute Determines whether a particular context is OK for the context attribute and returns a context property for a new context.
IContextProperty Gathers naming information from the context property and determines whether the new context is ok for the context property.
IContextPropertyActivator  
IContributeClientContextSink Contributes an interception sink at the context boundary on the client end of a remoting call.
IContributeDynamicSink The IContributeDynamicSink interface is implemented by properties that are registered at runtime through the RemotingServicesRegisterDynamicProperty API. These properties can contribute sinks that are notified when remoting calls start and finish.
IContributeEnvoySink The IContributeEnvoySink interface is implemented by context properties in the Server Context that wish to contribute an envoy message sink on the client end. The Server Envoy Chain is composed from those context properties that implement IContributeEnvoySink interface. The Envoy Chain lives on the client end and acts as representative of the corresponding message sinks from the server context properties.

See also Context.

IContributeObjectSink The IContributeObjectSink interface is implemented by context properties in a Context that wish to contribute an object specific interception sink on the server end of a remoting call.

The Server Object Chain is composed from those context properties in the server object's context that implement IContributeObjectSink interface. (Just-In-Time activation is an example of such a property, i.e. the message sink would activate the object after the call arrives and then pass the message on to the object.)

IContributeServerContextSink The IContributeServerContextSink interface is implemented by context properties in a Context that wish to contribute an interception sink at the context boundary on the server end of a remoting call.

The Server Context Chain is composed from those properties in the server context that implement IContributeServerContextSink interface and which contribute a sink via the GetServerContextSink method call. This chain is cached for future use. Thread Affinity could be an example of such a context property i.e. in this case the MessageSink would involve switching to a specific thread before processing a call further.

IDynamicMessageSink IDynamicMessageSink is implemented by message sinks provided by dynamically registered properties. These sinks are provided notifications of call-start and call-finish with flags indicating whether the call is currently on the client-side or server-side (this is useful for the context level sinks).
IDynamicProperty ??????????????????????????????????????
IEnvoyInfo Provides envoy information. Users can use this interface to provide custom envoy information that is carried along with the ObjRef.
ILease Distributed Garbage Collection (DGC) controls when server applications can be deleted. Traditionally DGC uses reference counts and pinging for control. This works well when there are a few clients per service, but doesn't scale well when there are thousands of clients per service. A Leasing Distributed Garbage Collector (LDGC) associates a lease time with each service. The service is deleted when the lease's time expires. The LDGC can subsume the function of a traditional DGC, in addition it scales well when the numbers of clients increase per server.
IMessage Messages can be thought of as a container for communicating data between co-operating, message sinks. These message sinks could be anywhere along the message sink chain: in the client sink chains or in the server sink chains. A message object is passed from message sink to message sink, through the chain and carries set of named properties such as, but not limited to, action identifiers, envoy information, and parameters.

An object that implements the interface IMessage meets the minimum qualification to be considered a message object. Also, there is no restriction that the exact object received by a message sink must be passed on to the next sink, though this will often be the case.

Although it is not a requirement that the objects in the property bag be serializable, it is certainly something that the message sink implementer would want to consider since an properties that need to flow out of the application domain will need to be serializable. Objects should also be agile if they are to be used in cross-context, same app-domain calls.

IMessageCtrl Provides a way to control asynchronous messages once they have dispatched via IMessageSink::AsyncProcessMessage.
IMessageSink When a method call is made on the proxy, the remoting infrastructure provides the necessary support for:

Passing the arguments to the actual object across the remoting boundaries.

Calling the actual object method with the arguments.

Returning the results back to the client of the proxy object.

A remote method call is defined in terms of a Message that goes from the client end to the server end and possibly back again. As it crosses interesting boundaries on the way, it passes through a chain of MessageSink objects. Each sink in the chain receives the Message object, performs a specific operation and delegates to the next sink in the chain. The Proxy object contains a reference to the first MessageSink it needs to use, to start off the chain.

For asynchronous calls, at the time of delegation, each sink provides a ReplySink (another MessageSink object) that will be called by the next sink when the reply is on its way back.

The nature of the operation performed by a MessageSink when it receives a Message object to process may be radically different for different types of sinks. For example, one sink could cause a lock to be taken, another could enforce call security, another could be performing flow call control/ reliability services and yet another could be responsible for transporting the call to a different AppDomain/ process/ machine. Two or more message sinks in the chain may communicate and interact with each other in regard to each specific action.

IMethodCallMessage [To be supplied.]
IMethodMessage [To be supplied.]
IMethodReturnMessage [To be supplied.]
IObjectHandle [To be supplied.]
IRemotingFormatter Provides the interface for all formatters.
IRemotingTypeInfo Interface for providing type information. Users can use this interface to provide custom type information that is carried along with the ObjRef.
ISchemaType [To be supplied.]
ISponsor  
ITrackingHandler The ITrackingHandler interface is called by Remoting when an event happens on an object or proxy.

Delegates

Delegate Description
CrossContextDelegate Every subclass of Delegate and MulticastDelegate has a constructor and an Invoke method. See the managed C++ code example given in the description for Delegate.

Delegate defined for context callbacks. It is expected to be a function on an agile object.

HeaderHandler The HeaderHandler delegate is used to process headers on the stream during serialization. Every subclass of Delegate and MulticastDelegate has a constructor and an Invoke method. See the managed C++ code example given in the description for Delegate.
MessageSurrogateFilter [To be supplied.]

Enumerations

Enumeration Description
LeaseState The different lease states are

Null:= The lease is not initialized.

Initial:=

Active:=

Renewing:=

Expired:=

WellKnownObjectMode