TransferMode Enum

Definition

Namespace:

System.ServiceModel

Assembly:

System.ServiceModel.Primitives.dll

Package:

System.ServiceModel.Primitives v8.0.0

Indicates whether a channel uses streamed or buffered modes for the transfer of request and response messages.

public enum class TransferMode

public enum TransferMode

type TransferMode = 

Public Enum TransferMode

Inheritance

Object

ValueType

Enum

TransferMode

Fields

Name	Value	Description
Buffered	0	The request and response messages are both buffered.
Streamed	1	The request and response messages are both streamed.
StreamedRequest	2	The request message is streamed and the response message is buffered.
StreamedResponse	3	The request message is buffered and the response message is streamed.

Examples

The following example sets the TcpTransportBindingElement.TransferMode property to Streamed through code:

TcpTransportBindingElement transport = new TcpTransportBindingElement();  
transport.TransferMode = TransferMode.Streamed;  
BinaryMessageEncodingBindingElement encoder = new BinaryMessageEncodingBindingElement();  
CustomBinding binding = new CustomBinding(encoder, transport);  

The following example sets the TcpTransportBindingElement.TransferMode property to Streamed through configuration:

<customBinding>  
    <binding name="streamingBinding">  
        <binaryMessageEncoding />  
            <tcpTransport transferMode="Streamed" />  
     </binding>  
</customBinding>  

Remarks

Windows Communication Foundation (WCF) transports support two modes of transferring messages in each direction:

• Buffered transfers hold the entire message in a memory buffer until the transfer is complete.

• Streamed transfers only buffer the message headers and expose the message body as a stream, from which smaller portions can be read at a time.

Setting the transfer mode to Streamed enables streaming communication in both directions. Setting the transfer mode to StreamedRequest or StreamedResponse enables streaming communication only in the indicated direction.

Streamed transfers can improve the scalability of a service by eliminating the need for large memory buffers. Whether changing the transfer mode actually improves scalability in practice depends on the size of the messages being transferred. Improvements in scalability should be most evident when large messages use streamed instead of buffered transfers.

By default, the HTTP, TCP/IP and named pipe transports use buffered message transfers. You can set the values of TransferMode on the BasicHttpBinding, NetTcpBinding, and NetNamedPipeBinding system-provided bindings using the transfer mode properties exposed on them. The mode can be set on the NetTcpBinding class, for example, by using the NetTcpBinding.TransferMode property. It can also be set in the configuration section for the binding.

For bindings that do not expose the transfer mode property, the transfer mode can be set on the binding element of the transport and this element can then be added to a custom binding. For example, create an HttpTransportBindingElement and use the TransferMode property to set the transfer mode when creating a custom binding. The transfer mode can also be set in the configuration section for the custom binding.

The decision to use either buffered or streamed transfers is a local decision of the endpoint for HTTP transports. For HTTP transports, the transfer mode does not propagate across a connection, or to proxy servers or other intermediaries. Setting the transfer mode is not reflected in the description of the service contract. After generating a proxy to a service, you can (it is allowed but not required) edit the configuration file for services intended to be used with streamed transfers to set the transfer mode. For TCP and named pipe transports, the transfer mode is propagated as a policy assertion.

Using the Streamed transfer mode causes the WCF runtime to enforce some restrictions.

• Operations that occur across a streamed transport can have a contract with at most one input and/or one output parameter at the programming model layer. That parameter corresponds to the entire body of the message and must be a Message, be a subtype of Stream, or implement the IXmlSerializable interface. Having a return value for an operation is equivalent to having an output parameter.

• Some WCF features such as Reliable Messaging and SOAP message-level security rely on buffering messages for transmissions. Using these features may reduce or eliminate the performance benefits gained by using streaming. To secure a streamed transport, use transport level security only or use mixed-mode security, which combines WS-Security claims with transport security.

• SOAP headers are always buffered, even when the transfer mode is set to Streamed. The headers for a message must not exceed the size of the MaxBufferSize transport quota which is exposed on the various bindings and binding elements.

Changing the transfer mode from Buffered to Streamed also changes the native channel shape of the TCP and named pipe transports. For buffered transfers, the native channel shape is IDuplexSessionChannel. For streamed transfers, the native channels are IRequestChannel and IReplyChannel. A consequence of this is that sessionful service contracts cannot be used with transport streaming.