<formatter> Element (Instance)

Article
10/23/2006

Contains the channel sink provider for a formatter sink that is to be inserted into the channel sink chain.

<configuration>
   <system.runtime.remoting>
      <channels>
         <channel>
            <serverProviders>
               <formatter/>

A formatter here overrides the default channel sink chain for this channel to become the new default for this channel template.

<configuration>
   <system.runtime.remoting>
      <channels>
         <channel>
            <clientProviders>
               <formatter/>

A formatter here overrides the default channel sink chain for this channel to become the new default for this channel template.

<configuration>
   <system.runtime.remoting>
      <application>
         <channels>
            <channel>
               <serverProviders>
                  <formatter/>

A formatter here overrides the default channel sink chain for this channel instance.

<configuration>
   <system.runtime.remoting>
      <application>
         <channels>
            <channel>
               <clientProviders>
                  <formatter/>

A formatter here overrides the default channel sink chain for this channel instance.

<formatter
   ref="FormatterReference"
   type="FormatterSinkProviderType, FormatterAssembly"
   customFormatterProperty="customProperty"
   includeVersions="true"
   strictBinding="false"
...typeFilterLevel="Low | High"
/>

Optional Attributes

Attribute	Description
customFormatterProperty	Indicates a supported custom formatter property. You can specify any number of formatter properties that custom formatters might support. A custom formatter property would be specified with an attribute/value pair. For example: `<formatter id="CustomFormatterSinkProvider" type="Namespace.CustomFormatterSinkProvider, CustomFormatters" customFormatterProperty="FormatterPropertyValue"/>`
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
type	Specifies the full type name of the formatter sink provider and the name of the assembly containing the provider implementation. This includes any version, culture, and public key information if the containing assembly is in the global assembly cache. This attribute is only required if you do not use a ref attribute.
ref	Specifies the ID of the formatter sink provider template for the formatter that your client intends to register for use. If you specify a ref attribute, you do not need to specify a type attribute.

Remarks

You can reference a provider template by using that template's id value as this instance's ref value. Although any number of templates can be declared, only one formatter sink can be in a channel sink call chain.

The <formatter> instance element can occur in four places. When specified underneath a <channel> template element (in either the <serverProvider> or <clientProvider> element), this element specifies a formatter that will override any channel default formatter to become the default formatter sink for that particular channel when the channel is referenced by an application <channel> instance. When specified underneath an <application> element, it overrides any formatter sink that might have been declared in the current channel instance or template.

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 xact 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

The following configuration file declares a <channel> instance that uses the <formatter> instance element to specify the default BinaryClientFormatterSinkProvider to use binary serialization with the HttpChannel.

<configuration>
   <system.runtime.remoting>
      <application>
         <channels>
            <channel ref="http">
               <clientProviders>
                  <formatter ref="binary"/>
               </clientProviders>
            </channel>
         </channels>
         <client>
            <wellknown 
               url="http://computername:80/RemoteType.rem" 
               type="RemoteType, RemoteAssembly"
            />
         </client>
      </application>
   </system.runtime.remoting>
</configuration>

Requirements

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