Channel and Formatter Configuration Properties
This topic lists and explains all configuration properties that you can specify for the IChannel implementations in the .NET remoting system. All values are represented by strings when you declare them in the configuration file, but when building the property IDictionary programmatically, integer values can be specified as integers (without quotes) or as strings (values within quotes), and Boolean values can be specified as Booleans. All other values are specified as strings. The following code example shows how the values might appear in a configuration file in a <channel> element. (Note that if you want to specify a template that uses a type that is in the global assembly cache, you must include all versioning and strong-name information to bind to the proper type.)
<channel
name="MyCustomChannel"
priority="2"
type="CustomChannelName, CustomAssembly, Version=1.0.6940.0, Culture=neutral, PublicKeyToken=somepublickeystring"
/>
The following code example shows how the values might appear if you were specifying this programmatically for a server application domain. In this case, the server is specifying that the remoting system should use a HttpChannel object for tranportation, but use a BinaryFormatter object for serialization and deserialization.
Dim props = New Hashtable() As IDictionary
props("name") = "ChannelName1"
Dim channel As New HttpChannel( _
props, _
Nothing, _
New BinaryServerFormatterSinkProvider() _
)
ChannelServices.RegisterChannel(channel)
[C#]
IDictionary props = new Hashtable();
props["name"] = "MyHttpChannel";
HttpChannel channel = new HttpChannel(
props,
null,
new BinaryServerFormatterSinkProvider()
);
ChannelServices.RegisterChannel(channel);
The following table shows the general channel properties that can be specified.
| Property | Description | Types that support this property |
|---|---|---|
| name | The name of this channel. If no name property is specified, the system defaults to "http" or "tcp". If you want to register more than one HttpChannel or TcpChannel, each must have a unique name. Set this property to an empty string ("" or String.Empty) if you want to ignore names, but avoid naming collisions. The system will allow any number of channels with name equal to String.Empty. This property is used to retrieve a specific channel when calling ChannelServices.GetChannel(). For details, see Channels. | HttpChannel HttpServerChannel HttpClientChannel TcpChannel TcpClientChannel TcpServerChannel |
| priority | An integer representing the priority assigned to this channel. Higher numbers indicate a higher chance of being chosen to connect first. The default priority is 1, and negative numbers are allowed. | HttpChannel HttpServerChannel HttpClientChannel TcpChannel TcpClientChannel TcpServerChannel |
The following table shows the client channel properties that can be specified.
| Property | Description | Types that support this property |
|---|---|---|
| clientConnectionLimit | An integer indicating how many connections can be simultaneously opened to a given server. The default is 2. | HttpChannel HttpClientChannel |
| proxyName | The name of the proxy computer. | HttpChannel HttpClientChannel |
| proxyPort | An integer specifying the proxy port. | HttpChannel HttpClientChannel |
| timeout | The number of milliseconds to wait before a request times out. -1 indicates an infinite timeout period. | HttpChannel HttpClientChannel |
| machineName | A string that specifies the machine name used with the current channel. Overrides the machine name specified in the channel data object.
It is generally a good idea to use the Domain Name System (DNS) name of the computer, but when the IP Address for a particular network interface card (NIC) (usually a wireless NIC) is changing rapidly, you must configure the application to use the machineName to enable remoting to find the machine through DNS. However, when the computer name does not resolve with reasonable speed (if at all) and when the computer has more than one NIC, either physical or virtual (this is often the case with a dial-up connection or VPN network adapter), you should set the machineName property to the IP address of the NIC that is currently in use for that connection. |
HttpChannel HttpClientChannel TcpChannel TcpClientChannel |
| allowAutoRedirect | Gets or sets a value indicating whether the automatic handling of server redirects is enabled. | HttpChannel HttpClientChannel |
| credentials | Gets or sets an ICredentials implementation that represents the identity of the client. | HttpChannel HttpClientChannel |
| useAuthenticatedConnectionSharing | A Boolean value indicating that the server channel will reuse authenticated connections rather than authenticate each incoming call. By default, this value is set to true if the useDefaultCredentials value is also set to true; otherwise, the value is set to false, which means that each call will be authenticated if the server requires authentication. This also applies to the programmatic equivalent, which is achieved either by creating an object that implements IDictionary, setting the "credentials" value to CredentialCache.DefaultCredentials, and passing that value to the channel sink, or by using the IDictionary returned from the ChannelServices.GetChannelSinkProperties method.
This name/value pair is supported only by version 1.1 of the .NET Framework on the following platforms: Microsoft Windows 98, Windows NT 4.0, Windows Millennium Edition (Windows Me), Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
HttpChannel HttpClientChannel |
| unsafeAuthenticatedConnectionSharing | A Boolean value indicating that the client will supply its own credentials and connection group name that the server should use to create an authenticated connection group. If this value is set to true, the connectionGroupName value must map to only one authenticated user. This name/value pair is ignored if the useAuthenticatedConnectionSharing value is set to true.
This name/value pair is supported only by version 1.1 of the .NET Framework on the following platforms: Windows 98, Windows NT 4.0, Windows Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
HttpChannel HttpClientChannel |
| connectionGroupName | The name that will be used as the connection group name on the server if the unsafeAuthenticatedConnectionSharing value is also specified. This name/value pair is ignored if unsafeAuthenticatedConnectionSharing is not set to true. If specified, make sure that this name maps to only one authenticated user.
This name/value pair is supported only by version 1.1 of the .NET Framework on the following platforms: Windows 98, Windows NT 4.0, Windows Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
HttpChannel HttpClientChannel |
Note On Windows 98 and Windows Me, there is no security ID to identify the authentication connection group name. Therefore, on these platforms there is one connection group name.
If you want your application to pass the ICredentials implementation or explicit username, password, and domain values in the HttpClientChannel properties, you can enable authentication connection sharing by also passing the unsafeAuthenticatedConnectionSharing name/value pair and the connectionGroupName name/value pair, making sure that the connectionGroupName value maps to only one authenticated user.
The following table shows the server channel properties that can be specified.
| Property | Description | Types that support this property |
|---|---|---|
| port | An integer specifying the port on which the channel will listen. | HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
| suppressChannelData | A Boolean value that specifies whether the channel will contribute to the channel data. | HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
| useIpAddress | A Boolean value that specifies whether to use the IP address in the publication URL instead of the computer name. For example, wireless networks often shuffle a portable computer's IP address as it moves throughout the network. Specifying false for this value causes the computer name to be used instead of the address, so that remote communications do not disconnect while roaming. The default is true. | HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
| bindTo | A string that specifies the IP address of the network interface card (NIC) to which the server channel should bind. | HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
| machineName | A string that overrides the computer name that is placed in the channel data. Specifying this property overrides useIpAddress. | HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
| listen | A Boolean value that specifies whether to allow activation to hook in IChannelReceiverHook.WantsToListen. | HttpChannel HttpServerChannel |
| rejectRemoteRequests | A Boolean value that specifies whether to refuse requests from other computers. Specifying true allows only remoting calls from the local computer. | TcpChannel TcpServerChannel |
| exclusiveAddressUse | A Boolean value that specifies whether the channel will prevent other applications from reusing the IP address/port combination. When set to true (the default), this property sets theSocketOptionName server socket option to SocketOptionName.ExclusiveAddressUse.
This property is supported only by the .NET Framework version 1.1 on the following platforms: Windows NT 4.0 with Service Pack 4 or later, Windows Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. This property requires administrator privileges on platforms prior to the Windows Server 2003 family. |
HttpChannel HttpServerChannel TcpChannel TcpServerChannel |
The following table shows the channel sink properties that can be specified.
| Property | Description | Types that support this property |
|---|---|---|
| includeVersions | A Boolean value that specifies whether the formatter should include versioning information. | BinaryClientFormatterSink BinaryServerFormatterSink SoapClientFormatterSink SoapServerFormatterSink |
| 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. The default for both system-provided formatters is false. For details, see <formatter> Element (Template). | BinaryServerFormatterSink, SoapServerFormatterSink |
| metadataEnabled | A Boolean value that specifies whether to honor requests that end in "?wsdl" if this sink is in the channel sink chain. The default setting is true. If false, the sink will throw an exception in all cases where metadata is requested for any object in the application domain.
This property is supported only by the .NET Framework version 1.1 on the following platforms: Windows 98, Windows NT 4.0, Windows Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
SdlChannelSink |
| remoteApplicationMetadataEnabled | A Boolean value that specifies whether to honor requests for the object Uniform Resource Identifier (URI) "RemoteApplicationMetadata?wsdl", which returns Web Services Description Language (WSDL) describing all objects published by the application domain. If false, any request to "RemoteApplicationMetadata.rem" will trigger an exception. All other "?wsdl" requests for particular object URIs will be honored. If true, the global metadata request will be honored. The default setting is false.
This property is supported only by the .NET Framework version 1.1 on the following platforms: Windows 98, Windows NT 4.0, Windows Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
SdlChannelSink |
| typeFilterLevel | A string value specifying the level of automatic deserialization that a server channel 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 Me, Windows 2000, Windows XP Home Edition, Windows XP Professional, and the Windows Server 2003 family. |
BinaryServerFormatterSink SoapServerFormatterSink |
See Also
Configuration | Remote Object Configuration | Remoting Settings Schema