<formatter> Element (Template)

  • Article

This topic is specific to a legacy technology that is retained for backward compatibility with existing applications and is not recommended for new development. Distributed applications should now be developed using the  Windows Communication Foundation (WCF).

Contains the channel sink provider for a formatter sink that is to be inserted into the client or server channel sink chain. There are two possible hierarchies for the inclusion of this element.

<configuration>

<system.runtime.remoting>

<channelSinkProviders>

<clientProviders>

<formatter>

A formatter provider specified here becomes a template for use by <formatter> instances.

<configuration>

<system.runtime.remoting>

<channelSinkProviders>

<serverProviders>

<formatter>

A formatter provider specified here also becomes a template for use by <formatter> instances.

<formatter  
   id="FormatterID"
   type="FormatterSinkProviderType, FormatterAssembly"
   customFormatterProperty="customProperty"
   includeVersions="true"
   strictBinding="false"
...typeFilterLevel="Low | Full"
/>

Optional Attributes

Attribute Description

customFormatterProperty

Indicates a supported custom channel sink property. You can specify any number of provider and channel sink properties that custom channel sink providers and their sinks might support. A custom channel sink property would be specified with an attribute/value pair. In the example:

<provider id="CustomChannelSinkProvider" type="Namespace.CustomChannelSinkProvider, CustomChannels" customChannelSinkProperty="ChannelSinkPropertyValue"/>

the customChannelSinkProperty attribute and its value will be available as an IDictionary argument in the constructor of the provider.

Custom sink provider data can also be specified here. Only one level of nodes is supported. In the example:

<provider ref="custom">
<extra data="value"/>
<extra data="AnotherValue"/>
</provider>

the extra information will be available as an ICollection of SinkProviderData in the constructor of the provider.

includeVersions

Indicates that a sending formatter includes complete type and assembly version information when serializing the type information. For important details, see the Remarks section below. The default for both system-provided formatters is true.

strictBinding

Indicates that a receiving formatter will first try to identify the type using complete version information if it exists before using only the type name and assembly name without version information. For important details, see the Remarks section below. The default for both system-provided formatters is false.

typeFilterLevel

A string value specifying the level of automatic deserialization a formatter in the server channel-sink chain attempts. Supported values are Low (the default) and Full. For details about deserialization levels, see Automatic Deserialization in .NET Remoting.

This property is supported only by the .NET Framework version 1.1 on the following platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family.

Required Attributes

Attribute Description

id

Specifies a string that identifies this formatter sink provider. Others can use this string in their ref attribute to bind to this formatter sink provider.

type

Specifies the full type name of the formatter sink provider and the name of the assembly containing the provider implementation. This includes version, culture, and public key information if the containing assembly is in the global assembly cache.

Remarks

A formatter specified here can be referenced by a <formatter> instance element elsewhere in this or in another configuration file loaded by the same application.

The following table describes the interaction between the includeVersions and strictBinding attributes when they appear together.

includeVersions (sending formatter) strictBinding (receiving formatter) How the type is loaded

true

true

The exact type is loaded, or a TypeLoadException is thrown.

false

true

The type is loaded using only the type name and the assembly name, or a TypeLoadException is thrown.

true

false

The exact type is loaded if present; if not, the type is loaded using only the type name and the assembly name. If that fails, a TypeLoadException is thrown.

false

false

The type is loaded using only the type name and the assembly name, or a TypeLoadException is thrown

Example

Because the following configuration file uses <clientProviders> instances, you must specify all the formatters and providers you want the channel to use. In this case, the <formatter> element references the SoapClientFormatterSink and uses a <provider> instance element to assign to the HttpChannel the "propsetter" and a "null" channel sink provider that themselves were declared with <provider> template elements. In addition, the "propsetter" channel sink provider is created with the custom provider properties specified as attributes on the provider instance element and as the child <endpoint> attribute name/value pairs.

<configuration>
   <system.runtime.remoting>
      <application>
         <client>
            <wellknown 
               type="RemoteType, RemoteAssembly"
               url="http://computername:8080/RemoteType.rem"/>
         </client>
         <channels>
            <channel ref="http">
               <clientProviders>
                  <formatter ref="soap"/>
                  <provider 
                     ref="propsetter" 
                     username="bob" 
                     writeToConsole="true"
                  >
                     <endpoint url="contoso.com:9000" someProperty="xyz" />
                     <endpoint url="contoso.com:9001" someProperty="123" />
                  </provider>
                  <provider ref="null" writeToConsole="true" />
               </clientProviders>
            </channel>
         </channels>
      </application>
      <channelSinkProviders>
         <clientProviders>
            <provider 
               id="propsetter" 
               type="ChannelSinkPropertySetterProvider, SinkAssembly" 
            />
            <provider 
               id="null" 
               type="NullSinkProvider, SinkAssembly" 
            />
         </clientProviders>
      </channelSinkProviders>
      <debug loadTypes="true" />
   </system.runtime.remoting>
</configuration>

Requirements

Configuration Files: Application configuration file, machine configuration file (Machine.config)

See Also

Reference

Remoting Settings Schema
BinaryClientFormatterSink
SoapClientFormatterSink
BinaryServerFormatterSink
SoapServerFormatterSink