<formatter> Element (Template)

Article
10/23/2006

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" password="xyz" />
                     <endpoint url="contoso.com:9001" password="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)

Partager via