This article is now a part of the Windows SDK.
Today's post is a short article about the mechanics of enabling transport streaming. This is a complement of other articles that describe how streaming works. Like the post on transport quotas, the formatting may be a little weird because I'm pasting these in from Word and it's HTML tag soup. Update: same content, less soup.
How to: Enabling Streaming
Windows Communication Foundation (WCF) transports support two modes for transferring messages. Buffered transfers hold the entire message in a memory buffer until the transfer is complete. Streamed transfers only buffer the headers and expose the message body as a stream, from which smaller portions can be read at a time. Streamed transfers can improve the scalability of a service by eliminating the need for large memory buffers. Whether changing the transfer mode will improve scalability depends on the size of the messages being transferred. Large message sizes favor using streamed transfers.
By default, the HTTP, TCP/IP and named pipe transports use buffered transfers. This document describes how to switch these transports from a buffered to streamed transfer mode and the consequences of doing so.
Enabling Streamed Transfers
Selecting between buffered and streamed transfer modes is done on the binding element of the transport. The binding element has a TransferMode property that can be set to Buffered, Streamed, StreamedRequest, or StreamedResponse. Setting the transfer mode to Streamed enables streaming communication in both directions. Setting the transfer mode to StreamedRequest or StreamedResponse enables streaming communication in the indicated direction only.
The BasicHTTPBinding exposes the TransferMode property on the binding. For other transports, you will need to create a custom binding to set the transfer mode.
The following code snippet shows setting the TransferMode property to streaming through code:
TcpTransportBindingElement transport = new TcpTransportBindingElement();transport.TransferMode = TransferMode.Streamed;BinaryMessageEncodingBindingElement encoder = new BinaryMessageEncodingBindingElement();CustomBinding binding = new CustomBinding(encoder, transport);
The following code snippet shows setting the TransferMode property to streaming through configuration:
<customBinding> <binding name="streamingBinding"> <binaryMessageEncoding /> <tcpTransport transferMode=”Streamed” /> </binding></customBinding>
The decision to use either buffered or streamed transfers is a local decision of the endpoint. For HTTP transports, the transfer mode does not propagate across a connection, or to proxy servers and other intermediaries. Setting the transfer mode is not reflected in the description of the service interface. After generating a proxy to a service, you will need to edit the configuration file for services intended to be used with streamed transfers to set the mode. For TCP and named pipe transports, the transfer mode is propagated as a policy assertion.
Restrictions of Streamed Transfers
Using the streamed transfer mode causes the runtime to enforce additional restrictions.
Differences Between Buffered and Streamed Transfers
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. This means that sessionful service contracts do not compose with transport streaming.
Next time: Five Pitfalls of the Channel Model, Part 1