<formatter> Element (Instance)

  • Artigo

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 channel sink chain. This element may occur in an application configuration file, machine configuration file.

<configuration>

<system.runtime.remoting>

<channels>

<channel>

<serverProviders>

<formatter> Element (Instance)

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> Element (Instance)

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> Element (Instance)

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

<configuration>

<system.runtime.remoting>

<application>

<channels>

<channel>

<clientProviders>

<formatter> Element (Instance)

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

Schema Hierarchy

<configuration>
  <system.runtime.remoting> Element
    <application> Element
      <channels> Element (Instance)
        <channel> Element (Instance)
          <clientProviders> Element (Instance)
            <formatter> Element (Instance)

Syntax

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

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute Description

ref

Required attribute.

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.

type

Required attribute.

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.

customFormatterProperty

Optional attribute.

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

Optional attribute.

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

Optional attribute.

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

Optional attribute.

A string value that specifies the level of automatic deserialization that 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.

Child Elements

None.

Parent Elements

Element Description

application

Contains information about remote objects that the application consumes and exposes.

channel

Contains the channel template that the application can specify and configure to communicate with or listen to requests for remote objects. Anywhere a channel can be registered for use, you can set the id attribute of that instance channel element to the ref attribute of this template.

channels

Contains channel templates that the application uses to communicate with remote objects. Channels declared under this element are available for referencing anywhere a channel is registered.

clientProviders

Contains providers for channel sinks that are to become part of the default client-side channel sink call chain for this channel template when the template is referenced elsewhere in the configuration file. Specifying providers in either position below overrides the default channel sinks for this channel; if you expect any of those default channel sinks to be inserted into the channel sink call chain for this template, you must specify them here.

configuration

The root element in every configuration file used by the common language runtime and .NET Framework applications.

system.runtime.remoting

Contains information about remote objects and channels.

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

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>

See Also

Reference

Remoting Settings Schema
BinaryClientFormatterSink
SoapClientFormatterSink
BinaryServerFormatterSink
SoapServerFormatterSink