How to: Enable Streaming

Article
08/07/2009

Windows Communication Foundation (WCF) can send messages using either buffered or streamed transfers. In the default buffered-transfer mode, a message must be completely delivered before a receiver can read it. In streaming transfer mode, the receiver can begin to process the message before it is completely delivered. The streaming mode is useful when the information that is passed is lengthy and can be processed serially. Streaming mode is also useful when the message is too large to be entirely buffered.

To enable streaming, define the OperationContract appropriately and enable streaming at the transport level.

To stream data

To stream data, the OperationContract for the service must satisfy two requirements:
1. The parameter that holds the data to be streamed must be the only parameter in the method. For example, if the input message is the one to be streamed, the operation must have exactly one input parameter. Similarly, if the output message is to be streamed, the operation must have either exactly one output parameter or a return value.
2. At least one of the types of the parameter and return value must be either Stream, Message, or IXmlSerializable.
The following is an example of a contract for streamed data.
```
[ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]
public interface IStreamingSample
{
    [OperationContract]
    Stream GetStream(string data);
    [OperationContract]
    bool UploadStream(Stream stream);
    [OperationContract]
    Stream EchoStream(Stream stream);
    [OperationContract]
    Stream GetReversedStream();

}
```
The GetStream operation receives some buffered input data as a string, which is buffered, and returns a Stream, which is streamed. Conversely UploadStream takes in a Stream (streamed) and returns a bool (buffered). EchoStream takes and returns Stream and is an example of an operation whose input and output messages are both streamed. Finally, GetReversedStream takes no inputs and returns a Stream (streamed).
Streaming must be enabled on the binding. You set a TransferMode property, which can take one of the following values:
1. Buffered,
2. Streamed, which enables streaming communication in both directions.
3. StreamedRequest, which enables streaming the request only.
4. StreamedResponse, which enables streaming the response only.
The BasicHttpBinding exposes the TransferMode property on the binding, as does NetTcpBinding and NetNamedPipeBinding. The TransferMode property can also be set on the transport binding element and used in a custom binding.

The following samples show how to set TransferMode by code and by changing the configuration file. The samples also both set the maxReceivedMessageSize property to 64 MB, which places a cap on the maximum allowable size of messages on receive. The default maxReceivedMessageSize is 64 KB, which is usually too low for streaming scenarios. Set this quota setting as appropriate depending on the maximum size of messages your application expects to receive. Also note that maxBufferSize controls the maximum size that is buffered, and set it appropriately.
1. The following configuration snippet from the sample shows setting the TransferMode property to streaming on the basicHttpBinding and a custom HTTP binding.
```
<basicHttpBinding>
  <binding name="HttpStreaming" maxReceivedMessageSize="67108864"
           transferMode="Streamed"/>
</basicHttpBinding>

<customBinding>
  <binding name="Soap12">
    <textMessageEncoding messageVersion="Soap12WSAddressing10" />
    <httpTransport transferMode="Streamed" maxReceivedMessageSize="67108864"/>
  </binding>
</customBinding>
```
2. The following code snippet shows setting the TransferMode property to streaming on the basicHttpBinding and a custom HTTP binding.
```
public static Binding CreateStreamingBinding()
{
    BasicHttpBinding b = new BasicHttpBinding();
    b.TransferMode = TransferMode.Streamed;
    return b;
}
```
3. The following code snippet shows setting the TransferMode property to streaming on a custom TCP binding.
```
public static Binding CreateStreamingBinding()
{
    TcpTransportBindingElement transport = new TcpTransportBindingElement();
    transport.TransferMode = TransferMode.Streamed;
    BinaryMessageEncodingBindingElement encoder = new BinaryMessageEncodingBindingElement();
    CustomBinding binding = new CustomBinding(encoder, transport);
    return binding;
}
```

The operations GetStream, UploadStream, and EchoStream all deal with sending data directly from a file or saving received data directly to a file. The following code is for GetStream.

public Stream GetStream(string data)
{
    //this file path assumes the image is in
    // the Service folder and the service is executing
    // in service/bin 
    string filePath = Path.Combine(
        System.Environment.CurrentDirectory,
        ".\\..\\image.jpg");
    //open the file, this could throw an exception 
    //(e.g. if the file is not found)
    //having includeExceptionDetailInFaults="True" in config 
    // would cause this exception to be returned to the client
    try
    {
        FileStream imageFile = File.OpenRead(filePath);
        return imageFile;
    }
    catch (IOException ex)
    {
        Console.WriteLine(
            String.Format("An exception was thrown while trying to open file {0}", filePath));
        Console.WriteLine("Exception is: ");
        Console.WriteLine(ex.ToString());
        throw ex;
    }
}

Writing a custom stream

To do special processing on each chunk of a data stream as it is being sent or received, derive a custom stream class from Stream. As an example of a custom stream, the following code contains a GetReversedStream method and a ReverseStream class-.

GetReversedStream creates and returns a new instance of ReverseStream. The actual processing happens as the system reads from the ReverseStream object. The ReverseStream.Read method reads a chunk of bytes from the underlying file, reverses them, then returns the reversed bytes. This method does not reverse the entire file content; it reverses one chunk of bytes at a time. This example shows how you can perform stream processing as the content is being read to or written from the stream.

class ReverseStream : Stream
{

    FileStream inStream;
    internal ReverseStream(string filePath)
    {
        //opens the file and places a StreamReader around it
        inStream = File.OpenRead(filePath);
    }
    public override bool CanRead
    {
        get { return inStream.CanRead; }
    }

    public override bool CanSeek
    {
        get { return false; }
    }

    public override bool CanWrite
    {
        get { return false; }
    }

    public override void Flush()
    {
        throw new Exception("This stream does not support writing.");
    }

    public override long Length
    {
        get { throw new Exception("This stream does not support the Length property."); }
    }

    public override long Position
    {
        get
        {
            return inStream.Position;
        }
        set
        {
            throw new Exception("This stream does not support setting the Position property.");
        }
    }

    public override int Read(byte[] buffer, int offset, int count)
    {
        int countRead = inStream.Read(buffer, offset, count);
        ReverseBuffer(buffer, offset, countRead);
        return countRead;
    }

    public override long Seek(long offset, SeekOrigin origin)
    {
        throw new Exception("This stream does not support seeking.");
    }

    public override void SetLength(long value)
    {
        throw new Exception("This stream does not support setting the Length.");
    }

    public override void Write(byte[] buffer, int offset, int count)
    {
        throw new Exception("This stream does not support writing.");
    }
    public override void Close()
    {
        inStream.Close();
        base.Close();
    }
    protected override void Dispose(bool disposing)
    {
        inStream.Dispose();
        base.Dispose(disposing);
    }
    void ReverseBuffer(byte[] buffer, int offset, int count)
    {

        int i, j;

        for (i = offset, j = offset + count - 1; i < j; i++, j--)
        {
            byte currenti = buffer[i];
            buffer[i] = buffer[j];
            buffer[j] = currenti;
        }

    }
}

Share via

How to: Enable Streaming

To stream data

Writing a custom stream

See Also

Concepts

Other Resources

Additional resources