Export (0) Print
Expand All
Expand Minimize

TransferMode Enumeration

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

Namespace:  System.ServiceModel
Assembly:  System.ServiceModel (in System.ServiceModel.dll)

'Declaration
Public Enumeration TransferMode

Member nameDescription
Supported in .NET for Windows Store appsBufferedThe request and response messages are both buffered.
Supported in .NET for Windows Store appsStreamedThe request and response messages are both streamed.
Supported in .NET for Windows Store appsStreamedRequestThe request message is streamed and the response message is buffered.
Supported in .NET for Windows Store appsStreamedResponseThe request message is buffered and the response message is streamed.

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, NetNamedPipeBinding system-provided bindings using the transfer mode properties exposed on them. The mode can be set on the NetTcpBinding, for example, by using the 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.

The following code sample shows setting the TransferMode property to Streamed through code:

c#

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

The following sample shows TransferMode property to Streamed through configuration:

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

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

.NET for Windows Store apps

Supported in: Windows 8

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft