Format for .NET Remoting Configuration Files

Article
04/30/2007

Piet Obermeyer and Jonathan Hawkins
Microsoft Corporation

September 2001
Updated March 2002

Summary: This article provides a detailed description of the schema used in remoting configuration files. (26 printed pages)

Contents

Introduction Hosting Remote Applications Why Register Channels Why Register Objects Settings Schema

Introduction

All remote objects have to be registered with the Remoting Framework before clients can access them. During this registration process, the Framework is provided with all the information required to activate and manage the lifetime of the object. The most important pieces of information required for registration is the type of the object, the URI where it will be deployed, the activation requirements for managing the object lifetime and the channels that can be used to connect to this object.

Although programmatic registration is a simple process, it is not always desirable to use for real-life applications where large numbers of remote objects have to be managed on a corporate network. Remoting configuration solves this problem by providing a simple mechanism for registering objects using configuration files, thereby allowing administrators to "tweak" the remoting settings without recompiling the application or services. This article details how remoting configuration can be used and describes the elements of the configuration file.

Hosting Remote Applications

Object registration is normally done by a hosting application that starts up, registers one or more channels with ChannelServices, registers one or more remote objects with RemotingServices and then waits until it is terminated. It is important to note that the registered channels and objects are only available while the process that registered them is alive. When the process quits, all channels and objects registered by that process is automatically removed from the remoting services where they were registered. The Configure method on RemortingConfiguration should be called to configure an object with a configuration file. This can easily be achieved as follows:

using System;
using System.IO;
using System.Runtime.Remoting;

public class MyHost {
  public static void Main(String[] args)
  {
    if (args.Length == 0) {
      // Perform a default configuration, throw an exception 
      // or display usage information to the user
    }
    else {
      RemotingConfiguration.Configure (args[0]);
    }
    // The program should pause here till the
    // registered objects are no longer required
  }

Configure loads the configuration file into memory, parses the contents and calls the relevant methods to register the channels and objects described in the file. There is nothing special about the Configure call, any host can load and parse the configuration file, extract the information required and register the object(s). It is important to note that remoting is not configured when a configuration file is loaded on application startup.

Why Register Channels

When a channel instance is registered with the framework, it starts listening for client requests on the protocol it was designed for. It is important to note that channels do not belong to any particular remote object. The same channel can service any number of remote objects.

During object registration, the Remote Object is marshaled to produce an ObjRef that stores all the relevant information required to activate and communicate with the remote object. Since the ObjRef is used to produce the TransparentProxy during unmarshalling, it requires knowledge of all the available channels to allow the client to make method calls on the remote object using the server protocols that are available to the client. All channels that are registered when the object is registered will be available to the client.

Why Register Objects

The remoting framework is responsible for activating remote objects and managing their lifetime. In order to do this, it stores a list of all registered objects keyed on the object URI. When a client calls a method on the proxy, the method call is turned into a message that is then transported over the relevant channel to the application domain specified in the URL specified by the client. When the call arrives at the server (the application domain where the object is hosted), the framework uses the ObjectUri to locate the ObjRef of the object in the identity table. If the ObjRef is found, the framework activates the object if necessary and forwards the method call to the object.

There are 2 different types of server-activated objects namely:

Well-known objects of type SingleCall maintain no state between method invocations. A new instance of the object will be created for each method call made on the object. When the call completes, an optional result will be returned to the caller and the object will be recycled.
Singleton objects do maintain state between method invocations. When the object is registered the framework instantiates a single instance of the object. All method calls made on this object will be routed to the single instance created. It is the developers' responsibility to ensure singleton objects are suitably protected to function in a multi-threaded environment.

Well-known objects can only be published/marshaled in the AppDomain in which they were created.

When context-bound objects are created, a compatible context is required. First the current context is checked for compatibility with the context property requirements of the objects, if that fails, then a matching context is created that meets the context property requirements for the object. See the context section for further details.

When a server object is marshaled, the server object sink chain, which leads to the object, is built. The stack builder sink is the last sink in the server object chain and communicates with the server object directly. The stack builder sink is provided by the remoting infrastructure. When a server object that is context-bound is marshaled, the reference to the context in which the object was created is stored in the entry in the identity table.

When inbound calls arrive, they are dispatched on the server object. The identity table provides the URI to object, context and message sink chain mapping.

Settings Schema

Contains tags used to put custom settings in remoting application configuration files.

Element	Description
<configuration>	This is root of all elements in a configuration file
<system.runtime.remoting>	All remoting configurations should be placed inside this tag. Only one of these elements is allowed.
<application>	All application-specific information should be placed inside this tag. Only one of these elements is allowed.
<lifetime>	Should be placed under the <application> tag. This lifetime applies to all client-activated objects as well as singletons provided as a service. Only one of these elements is allowed.
<channel> (template)	The <channel> node is used to provide channel templates that can be referenced elsewhere in the .config file. A default channel implementation is provided in the machine.config file so users don't have to concern themselves with setting up templates for the default http and tcp channels. Only one of these elements is allowed.
<channels> (template)	A <channels> node can be placed inside the <system.runtime.remoting> tag to provide a container for channel templates. Only one of these elements is allowed.
<channels> (application)	A <channels> node can be placed inside the <application> tag to configure channels declared in the <channel> template or to declare new channels. Only one of these elements is allowed
<channel> (application)	Zero or more <channel> tags can be placed inside the application channel node to configure individual channels. Remember that attributes placed on a channel are determined by the channel, not by remoting per se. For example, someone can build an entirely new channel that does not require any of the attributes we describe in this document.
<channelSinkProviders>	Sink-provider information is specified under this tag. Any channel sink providers specified here can be referenced anywhere a channel sink provider might be registered. Only one of these elements is allowed.
<serverProviders>	Specify sink providers that will be used on the server side here. The default entry in the machine.config file specifies the binary and SOAP formatters as well as a WsdlChannelSinkProvider. <serverProviders> tags can also be placed inside a <channel> tag to configure providers specified in <channelSinkProviders>. Only one of these elements is allowed.
<clientProviders>	Specify sink providers that will be used on the client side here. The default entry in the machine.config file specifies the SOAP and binary formatters. <clientProviders> tags can also be placed inside a <channel> tag to configure providers specified in <channelSinkProviders>. Only one of these elements is allowed.
<provider>	Contains the channel sink provider for a channel sink that is to be inserted into the channel sink chain. This tag can be placed under <serverProvider> or <clientProvider>. Zero or more of these elements are allowed.
<formatter>	Contains the channel sink provider for a formatter sink that is to be inserted into the channel sink chain. This tag can be placed under <serverProvider> or <clientProvider>. Zero or more of these tags are allowed.
<service>	Zero or more service tags can be specified under <application>. All objects to be hosted are listed here. Remoting has two types of hosting direct and IIS. For direct hosting, the .config file is normally stored with the hosting application. When hosting in IIS, the .config file must be called web.config and placed in the vroot. The DLL containing the service is placed in the bin directory directly under the vroot. Contains objects the application exposes to other application domains or contexts.
<wellknown>	Contains information about server-activated (well-known) objects the application wants to publish. Zero or more of these elements can be placed under the <service> or <client> tags.
<activated>	Contains information about client-activated objects the application wants to publish. Zero or more of these elements can be placed under the <service> or <client> tags.
<client>	Zero or more client tags can be specified under <application>. Specifies objects the application consumes.
<soapInterop>	Contains type mappings used with SOAP.
<interopXmlType>	Creates a bidirectional map between a common language run time type and an XML element and XML namespace when the element name cannot be changed. Only one of these elements is allowed.
<interopXmlElement>	Creates a bidirectional map between a common language run time type and an XML element and XML namespace. Can occur one or more times.
<preLoad>	Load mappings for all classes that extend SoapAttribute. Can occur one or more times.
<debug>	Specifies whether to load types in the configuration file when the application starts. This element cannot be specified when the configuration file is named web.config and the remote type is hosted in IIS.

<configuration>

Parent Element:

None

Description:

This is root of all elements in a configuration file.

Child Elements:

system.runtime.remoting

Required Attributes:

None

Optional Attributes:

None

<system.runtime.remoting>

Parent Element:

configuration

Description:

All remoting configuration should be placed inside this tag. Only one of these elements is allowed.

Child Elements:

application, channelSinkProviders, channels, debug

Required Attributes:

None

Optional Attributes:

Version: System.runtime.remoting can be followed by an optional version number. The only version currently allowed is v1. This is specified as follows:

<system.runtime.remoting version="1.0">

It is important to note that this version number is not the version of the assembly, but the version of the configuration file reader. This attribute ensures that we will be able to provide a reader that is backwards compatible if the configuration file format is changed in future.

<application>

Parent Element:

system.runtime.remoting

Description:

All application-specific information should be placed inside this tag. Only one of these elements is allowed.

Child Elements:

lifetime, service, client, channels, soapInterop

Required Attributes:

None

Optional Attributes:

Name: The application tag can be followed by an optional name. This is specified as follows:

<application name="RemotingHello">

If a name is supplied on the service side, the objectURI is appended to the name to determine the endpoint clients connect to. For example, if the name is RemotingHello and the object URI is HelloService.soap, clients should connect to the service as follows:

http://someMachine/RemotingHello/HelloService.soap

If no application name is used, clients should connect to:

http://someMachine/HelloService.soap

<lifetime>

Parent Element:

application

Description:

This lifetime applies to all client activated objects as well as singletons provided as a service. Only one of these elements is allowed.

Child Elements:

None

Required Attributes:

None

Optional Attributes:

leaseTime: is the lease time for the application. The default value is 5 minutes.

sponsorshipTimeout: is the time the lease manager waits for the sponsor to respond when notified that a lease has expired. If the sponsor does not respond in the specified time, the remote object is garbage collected. The default value is 2 minutes.

renewOnCallTime: is the lease time of the object and is extended with every method called on the object. The default value is 2 minutes.

leaseManagerPollTime: is the amount of time the lease manager sleeps after checking for expired leases. The default value is 10 seconds.

Lifetime can be specified as follows:

<lifetime leaseTime="20ms" sponsorshipTimeOut="20ms" 
renewOnCallTime="20ms" />

This lifetime applies to all client activated objects as well as singletons provided as a service. Although not illegal, lifetime will have no effect when added to a configuration file of an application that only consumes services—in other words, it applies to service objects only.

Valid time units are D for days, H for hours, M for minutes, S for seconds, and MS for milliseconds. If no unit is specified, the time provided is assumed to be in seconds.

<service>

Parent Element:

application

Description:

Zero or more elements are allowed. All objects to be hosted are listed under this tag. Remoting has two types of hosting: direct and via IIS. For direct hosting, the configuration file is normally stored with the hosting application. When hosting in IIS, the configuration file must be called web.config and placed in the vroot. The DLL containing the service is placed in the bin directory directly under the vroot or published in the GAC.

Child Elements:

wellknown, activated

Required Attributes:

None

Optional Attributes:

None

<client>

Parent Element:

application

Description:

Zero or more client tags can be specified under <application>. Specifies objects the application consumes.

Child Elements:

wellknown, activated

Required Attributes:

url: is only required for client-activated types. Specifies the URL that will be used to locate the activator for the attribute.

Optional Attributes:

displayName: is only used by the Admin Tool to allow users to differentiate between the different objects listed when more than one client tag is present in the configuration file.

<wellknown>

Parent Element:

service, client

Description:

Specifies the server-activated or well-known objects provided by the service. Zero or more of these elements can be specified.

Child Elements:

None

Required Attributes:

mode: is the type of server-activated object. Valid values for this attribute are Singleton and SingleCall.

type: is the full type name (type,assembly) of the object.

objectUri: specifies the URI of the remote object which is the name of the "endpoint" remote objects will connect to. This attribute can only be used in the <service> tag. The .soap extension is required when the object will be accessed via IIS. This extension is case insensitive.

url: specifies the URL that should be used to connect to the service. This attribute can only be used in the <client> tag.

Optional Attributes:

displayName: when present (in a <client> tag) is used by the Admin Tool to allow users to differentiate between the different objects listed when more than one well-known object is listed in the <client> section of the configuration file.

Example:

The example below shows how to use this element when defining a well-known service.

<configuration>
  <system.runtime.remoting>
    <application>
      <service>
        <wellknown mode="SingleCall" type="Hello.HelloService, Hello" 
objectUri="HelloService.soap" />
      </service>
    </application>
  </system.runtime.remoting>
</configuration>

The example below shows how this element is used in the <client> tag.

<configuration>
  <system.runtime.remoting>
    <application>
      <client>
        <wellknown type="Hello.HelloService, Hello" 
url="https://localhost:8000/HelloService.soap" />
      </client>
    </application>
  </system.runtime.remoting>
</configuration>

<activated>

Parent Element:

service, client

Description:

Specifies the client-activated objects the application wants to publish. Zero or more of these elements can be placed under the <service> or <client> tags.

Child Elements:

None

Required Attributes:

type: is the full type name (type,assembly) of the object. This tag can be used with the <service> as well as <client> tags.

Optional Attributes:

None

Example:

The example below shows how to use this element when defining a client-activated service.

<configuration>
  <system.runtime.remoting>
    <application>
      <service>
        <activated type="Hello.AddService, Hello"/>
      </service>
    </application>
  </system.runtime.remoting>
</configuration>

The example below shows how this element is used in the <client> tag.

<configuration>
  <system.runtime.remoting>
    <application>
      <client url="https://localhost:8000>
        <activated type="Hello.AddService, Hello"/>
      </client>
    </application>
  </system.runtime.remoting>
</configuration>

<channels>

Parent Element:

system.runtime.remoting, application

Description:

When this element is placed inside the <application> tag, it is used to configure existing channels defined under <system.runtime.remoting>. To define new channels, place a <channels> tag directly under <system.runtime.remoting>. Default channels are defined in the machine.config file, so unless you are registering a new channel, there is no need to define any channels at this level.

Child Elements:

channel

Required Attributes:

None

Optional Attributes:

None

Example:

<configuration>
  <system.runtime.remoting>
    <application>
      <channels>
      </channels>
    </application>
    <channels>
    </channels>
  </system.runtime.remoting>
</configuration>

<channel>

Parent Element:

Either of the channel tags described above in the <channels> section.

Description:

Zero or more <channel> tags can be placed inside the application channel node to configure individual channels. Remember that the attributes placed on a channel are determined by the channel, not by remoting. For example, someone can build an entirely new channel that does not require any of the attributes we describe in this document.

Child Elements:

Child elements can be clientProviders and serverProviders when the parent <channels> tag is placed under <system.runtime.remoting>. When the parent is placed under the <application> tag, only channels that have already been declared can be referenced.

Required Attributes:

The following attributes are required when declaring channel templates. The <channels> tag is placed under <system.runtime.remoting>. You can also declare a channel in the application section and provide all the attributes for the channel as part of this declaration.

id: specifies a name for the channel that can be used when referring to it. If we name the channel "tcp" for example, we can refer to it under the application channel tag. Duplicate ID's are not allowed and the parser won't throw an exception if duplicates are encountered—the last one found will be the ID associated with the channel.

type: is the full type name of the channel that will be loaded.

ref: is the channel template being referenced. The value specified for this attribute is used to find the channel being referenced by matching the channel id's specified on the machine level. Channels are normally referenced to provide values to channel attributes. For example, if we need to use the TCP channel defined in the machine.config file on port 8000, we simple reference the channel in the application section and provide a port number for it. It is important to note that you cannot reference an existing channel template from the template section.

Optional Attributes:

The following optional attributes can be used when declaring channel templates.

name: specifies the name of the channel. It is sometimes necessary to configure the same channel more than once. For example, let us assume we need the TCP channel to listen on both port 8000 and well as 9000. If you attempt to reference the same channel more than once, specifying a different channel number for each, an exception is thrown since you cannot register the same channel more than once. The proper way to do this is to add the "name" attribute to each of the channel references and specifying a different name for each (see the example below).

priority: specifies a preference for the channel that should when determining how the connection to the service will be made. When you attempt to connect to a remote object, remoting uses the information specified in the URL to search for the channel that can handle the request. The first channel that indicates it can handle the request is the one that will be used. This attribute allows you to express a preference in channel selection. All the default channels provided with the SDK default to priority 1. Higher numbers mean higher priority (negative numbers are allowed). Channels with higher priority get the first chance at connecting to an object on the client side, and when acting as server channels, their channel data will be looked at first.

displayName: is used by the Admin tool to display channel information to users. This attribute is only used in the template section.

delayLoadAsClientChannel: specifies whether this channel should be loaded if the client does not register a channel for the application. This value is a Boolean, and only affects client behavior. The value true indicates that .NET Remoting should test this channel at run time to see whether it supports a client connection using the particular protocol scheme specified in the remote activation URL. If the value is not present, the default value is false.

customChannelProperty: specifies a name /.value pair for channel attributes. Channel properties are not specified by remoting, each channel implementation has its own requirements. The term customChannelProperty is only used here for discussion purposes.

<channel id="CustomChannel" type="Namespace.CustomChannel, CustomChannels" myProperty="myValue"/>

The following attributes can be used for application channels.

Configuring the http channel:

The http channel has the following additional optional attributes.

port: is any valid port number. The port the channel should listen on.

clientConnectionLimit: specifies how many connections can be simultaneously opened to a given server. The default is 2. This is exactly the same as the connection limit on ServicePoint in the net classes.

proxyName: allows you to configure the channel for use with a proxy server. The name of the proxy server goes here

proxyPort: allows you to configure the channel for use with a proxy server. The port number to use goes here.

listen: specify true here if you want IChannelReceiverHook.WantsToListen on to be called on the channel during activation. If there are no listening channels, remoting will register one of its own. If you set a port number, this attribute will be set to false.

suppressChannelData: set this value to false if the channel does not contribute ChannelData for the ObjRef.

useIpAddress: allows you to determine if the IP address or machine name is used in the URL. This attribute is only used on the server side and the default value is true.

bindTo: specify an IP address of the NIC to bind to when more than one NIC is installed in a machine. This attribute can only be used in the server side.

machineName: overrides the machine name that will be used in the channel data. This attribute overrides useIpAddress.

Configuring the TCP channel:

The TCP channel has the following additional optional attributes.

port: any valid port number. The port the channel should listen on.

suppressChannelData: set this value to false if the channel does not contribute ChannelData for the ObjRef.

useIpAddress: allows you to determine if the IP address or machine name is used in the URL. This attribute is only used on the server side and the default value is true.

rejectRemoteRequests: refuse connections from other machines. When this attribute is set to true, only cross-process connections will be allowed.

bindTo: specify an IP address of the NIC to bind to when more than one NIC is installed in a machine. This attribute can only be used in the server side.

Example

This example below shows how to declare a channel in the application section.

<configuration>
  <system.runtime.remoting>
    <application name="RemotingHello">
      <lifetime leaseTime="20ms" sponsorshipTimeOut="20ms" 
renewOnCallTime="20ms" />  
      <service>
        <wellknown mode="SingleCall" type="Hello.HelloService, MyHello, 
Version=1.0.0.0, PublicKeyToken=bef6d8db915d3112,Culture=Neutral" 
objectUri="HelloService.soap" />
        <activated type="Hello.AddService, MyHello"/>
      </service>
      <channels>
        <channel pipename="mypipe" 
type="Microsoft.Samples. Runtime.Remoting.Channels.Pipe.PipeChannel, 
Microsoft.Samples.Runtime.Remoting.Pipe">
         </channel>  
      </channels>
    </application>
  </system.runtime.remoting>
</configuration>

This following example shows how to declare a channel in the template section and reference it from the application section.

<configuration>
  <system.runtime.remoting>
    <application name="RemotingHello">
      <lifetime leaseTime="20ms" sponsorshipTimeOut="20ms" 
renewOnCallTime="20ms" />  
      <service>
        <wellknown mode="SingleCall" type="Hello.HelloService, MyHello, 
Version=1.0.0.0, PublicKeyToken=bef6d8db915d3112,Culture=Neutral" 
objectUri="HelloService.soap" />
        <activated type="Hello.AddService, MyHello"/>
      </service>
      <channels>
        <channel ref="pipe1" name="foo1" pipename="mypipe" />
      </channels>
    </application>
    <channels>
      <channel id="pipe1" 
type="Microsoft.Samples.Runtime.Remoting.Channels.Pipe.PipeChannel, 
Microsoft.Samples.Runtime.Remoting.Pipe">
       </channel> 
    </channels>
  </system.runtime.remoting>
</configuration>

<channelSinkProviders>

Parent Element:

system.runtime.remoting

Description:

All channel sink related tags should be placed under this tag. Only one of these elements is allowed.

Child Elements:

clientProviders, serverProviders

Required Attributes:

None

Optional Attributes:

None

<serverProviders>

Parent Element:

system.runtime.remoting, channel

Description:

When this element is placed inside the <channel> tag, it is used to configure existing sink providers defined under <system.runtime.remoting>. This element can be placed under either <channel> tag (a template or the one in application). To define new sink providers, place a <serverProviders> tag directly under <system.runtime.remoting>. We also define default sink providers in the machine.config file, so unless you are registering a new sink provider, there is no need to define any providers at this level. Only one of these elements is allowed.

Child Elements:

formatter, provider

Required Attributes:

None

Optional Attributes:

None

Remarks:

It is important to realize that all default providers or formatters for a channel are overridden if this element references or declares formatters or providers in a <channel> element. In this case you need to specify all providers and the formatter to be used with the channel. The order in which providers and formatters are listed is the order in which the sink chain will be assembled. Adding a provider before a formatter on the client side, for example, will throw an exception if the provider does not implement the required interfaces for a formatter.

<clientProviders>

Parent Element:

system.runtime.remoting, channel

Description:

When this element is placed inside the <channel> tag, it is used to configure existing sink providers defined under <system.runtime.remoting>. To define new sink providers, place a <clientProviders> tag directly under <system.runtime.remoting>. Default sink providers are defined in the machine.config file, so unless you are registering a new sink provider, there is no need to define any providers at this level. Only one of these elements is allowed.

Child Elements:

formatter, provider

Required Attributes:

None

Optional Attributes:

None

Remarks:

It is important to realize that all default providers or formatters for a channel are overridden if this element references or declares formatters or providers in a <channel> element. In this case you need to specify all providers and the formatter to be used with the channel. The order in which providers and formatters are listed is the order in which the sink chain will be assembled. Adding a provider before a formatter on the client side for example, will throw an exception if the provider does not implement the required interfaces for a formatter.

<provider>

Parent Element:

clientProviders, serverProviders

Description:

The specified channel sink provider for a channel sink that will be inserted into the channel sink chain. This tag can be placed under <serverProvider> or <clientProvider>. Zero or more of these elements are allowed.

Child Elements:

None

Required Attributes:

id: the id specifies the name you use in the application section to reference the provider.

type: the type specifies the class/assembly that need to be instantiated for this provider.

ref: specify the ID of the provider template that the channel intends to use. This attribute cannot be used in the provider template itself.

Optional Attributes:

Properties: specifies additional properties for the provider. The properties to be specified are determined by the providers themselves. The name of the XML tag is not important since all data under the node will be passed in as a DOM structure.

Any XML attributes on the node and any XML sections underneath the provider node will be "packaged up" and passed to the constructor of the provider when remoting creates the providers specified in a configuration file. All providers specified in a configuration file must have a constructor that takes an IDictionary and ICollection as parameters. The dictionary will contain the XML attributes specified on the provider node. The collection is always a collection of SinkProviderData which is a DOM structure of the subnodes.

Example:

<configuration>
<system.runtime.remoting>
<application name="MyFoo">
  <service>
    <wellknown type="Foo, common" objectUri="Foo.soap" mode="Singleton" 
/>
  </service>
  <channels>
    <channel ref="http server" name="MyHttpChannel" port="9000">
      <serverProviders>        
        <provider ref="ip filter" mode="accept">
          <filter mask="255.255.255.255" ip="127.0.0.1" />          
        </provider>
        <formatter ref="soap" />
      </serverProviders>
    </channel>
  </channels>
</application>
<channelSinkProviders>
  <serverProviders>
    <provider id="ip filter" 
type="IPFilter.IPFilterChannelSinkProvider, IPFilterSink" />
  </serverProviders>
</channelSinkProviders></system.runtime.remoting>
</configuration>

<formatter>

Parent Element:

clientProviders, serverProviders

Description:

Used to specify a formatter that will be inserted into the channel sink chain. This tag can be placed under <serverProvider> or <clientProvider>. Zero or more of these elements are allowed.

Child Elements:

None

Required Attributes:

id: the id specifies the name you use in the application section to reference the formatter.

type: the type specifies the class/assembly that need to be instantiated for this formatter.

ref: specify the ID of the formatter template that the channel intends to use. This attribute cannot be used in the formatter template itself.

Optional Attributes:

includeVersions: specifies that the formatter should include full versioning when serializing types.

strictBinding: specifies that the formatter should not use partial binds when deserializing objects. When set to false, types are loaded using their strong names. If this fails, the type will be loaded using partial binds. If this fails, an exception will be thrown.

Properties: specifies additional properties for the formatter. The properties that can be specified are determined by the formatters themselves. The name of the XML tag is not important since all data under the node will be passed in as a DOM structure.

Any XML attributes on the node and any XML sections underneath the formatter node will be "packaged up" and passed to the constructor of the formatter when remoting creates the formatters specified in a configuration file. All formatters specified in a configuration file must have a constructor that takes an IDictionary and ICollection as parameters. The dictionary will contain the XML attributes specified on the formatter node. The collection is always a collection of SinkProviderData which is a DOM structure of the subnodes.

<soapInterop>

Parent Element:

system.runtime.remoting

Description:

Specifies type mappings used with SOAP.

Child Elements:

preLoad, interopXmlElement, interopXmlType

Required Attributes:

None

Optional Attributes:

None

<preLoad>

Parent Element:

soapInterop

Description:

Load mappings for all classes that extend SoapAttribute. Although these types will be picked up automatically for serialization, the .NET Remoting system requires these configuration elements (or calling the programmatic equivalent) to deserialize properly.

Child Elements:

None

Required Attributes:

None

Optional Attributes:

type: specifies the type to preload to enable deserialization.

assembly: preload all types in the specified assembly.

Example

The following example associates the element ElementName and the XML namespace Example:mynamespace with the .NET type TypeName implemented by the AssemblyName assembly. The same is true of the XML type and namespace.

<configuration>
   <system.runtime.remoting>
      <application name="soapInterop">
         <soapInterop>
            <interopXmlElement 
               xml="ElementName,Example:mynamespace"                
clr="TypeName,AssemblyName"
            />
            <interopXmlType  
               xml="XmlTypeName,Example:TypeNamespace" 
               clr="TypeName,AssemblyName"
            />
            <preLoad
               type="TypeName"
               assembly="AssemblyName"
         </soapInterop>
      </application>
   </system.runtime.remoting>
</configuration>

<interopXmlElement>

Parent Element:

soapInterop

Description:

Creates a bidirectional map between a common language run time type and an XML element and XML namespace. Can occur one or more times.

Child Elements:

None

Required Attributes:

clr: specifies the full type name and assembly name of the type for which you want to create a mapping to the XML element and XML namespace.

xml: specifies the XML element and the XML namespace for which you want to create a mapping to a type and assembly.

Optional Attributes:

None

Example:

The following example associates the element ElementName and the XML namespace Example:mynamespace with the .NET type TypeName implemented by the AssemblyName assembly. The same is true of the XML type and namespace.

<configuration>
   <system.runtime.remoting>
      <application name="soapInterop">
         <soapInterop>
            <interopXmlElement 
               xml="ElementName,Example:mynamespace"                
clr="TypeName,AssemblyName"
            />
            <interopXmlType  
               xml="XmlTypeName,Example:TypeNamespace" 
               clr="TypeName,AssemblyName"
            />
         </soapInterop>
      </application>
   </system.runtime.remoting>
</configuration>

<interopXmlType>

Parent Element:

soapInterop

Description:

Creates a bidirectional map between a common language run time type and an XML element and XML namespace when the element name cannot be changed. Only one of these elements is allowed.

Child Elements:

None

Required Attributes:

clr: specifies the full type name and assembly name of the type for which you want to create a mapping for to an XML type and XML namespace.

xml: specifies the XML type name and the XML type namespace for which you want to create a mapping to a type and assembly.

Optional Attributes:

None

Example:

The following example associates the element ElementName and the XML namespace Example:mynamespace with the .NET type TypeName implemented by the AssemblyName assembly. The same is true of the XML type and namespace.

<configuration>
   <system.runtime.remoting>
      <application name="soapInterop">
         <soapInterop>
            <interopXmlElement 
               xml="ElementName,Example:mynamespace"                
clr="TypeName,AssemblyName"
            />
            <interopXmlType  
               xml="XmlTypeName,Example:TypeNamespace" 
               clr="TypeName,AssemblyName"
            />
         </soapInterop>
      </application>
   </system.runtime.remoting>
</configuration>

<debug>

Parent Element:

system.runtime.remoting

Description:

Specifies whether to load types in the configuration file when the application starts. This element cannot be specified when the configuration file is named web.config and the remote type is hosted in IIS.

Child Elements:

None

Required Attributes:

loadTypes: specifies whether to load all types specified in the configuration file when the application starts. This helps to prevent simple typing errors from becoming an annoying debugging effort.

Optional Attributes:

None

Example:

The following configuration file example tells the .NET Remoting system to attempt to load the types specified in this file (in this case, the ServiceClass and TcpChannel types) when the client application starts.

<configuration>
   <system.runtime.remoting>
      <application>
         <client>
            <wellknown 
               type="ServiceClass, IService"
               url="tcp://computername:8080/TcpService"
            />
         </client>
         <channels>
            <channel ref="tcp"/>
         </channels>
      </application>
      <debug loadTypes="true" />
   </system.runtime.remoting>
</configuration>

Naming conventions for configuration files

Configuration files are also used to store such setting as binding policy and security. All EXE and COM hosts automatically generate a configuration file for the application domains they create. The name of this configuration file is the full module name including the extension. So, for foo.exe, the configuration file name will be foo.exe.config. Although .NET remoting does not mandate what the name of the configuration file should be, developers are advised to use the naming convention outlined above to ensure that security and binding policies specified is picked up when the application is executed.

The name of the application configuration file can be retrieved from the AppDomain as follows

String configfilename = 
AppDomain.CurrentDomain.SetupInformation.ConfigurationFile;

In some situations it might be desirable to use more than one configuration file to configure a remote application. Developers should therefore ensure that they don't use these additional remoting configuration files for storing security or binding policies, since these will not be read when the application is executed. The configure call on RemotingConfiguration only reads the relevant sections in the configuration file that applies to remoting, the rest of the information is ignored.

Format for .NET Remoting Configuration Files

Introduction

Hosting Remote Applications

Why Register Channels

Why Register Objects

Settings Schema

<configuration>

<system.runtime.remoting>

<application>

<lifetime>

<service>

<client>

<wellknown>

<activated>

<channels>

<channel>

<channelSinkProviders>

<serverProviders>

<clientProviders>

<provider>

<formatter>

<soapInterop>

<preLoad>

<interopXmlElement>

<interopXmlType>

<debug>

Naming conventions for configuration files

Additional resources