Edit

Share via

BufferedStream.WriteByte no longer performs implicit flush

The BufferedStream.WriteByte(Byte) method no longer performs an implicit flush when the internal buffer is full. This change aligns the behavior of BufferedStream.WriteByte with other Write methods in the BufferedStream class, such as BufferedStream.Write(Byte[], Int32, Int32) and BufferedStream.WriteAsync(Byte[], Int32, Int32, CancellationToken), which don't perform an implicit flush.

Version introduced

.NET 10 Preview 4

Previous behavior

Previously, when the internal buffer of a BufferedStream was full, calling WriteByte automatically flushed the buffer to the underlying stream. This behavior was inconsistent with other Write methods in BufferedStream.

The following example demonstrates the previous behavior:

StreamWithFlush streamWithFlush = new();
BufferedStream bufferedStream = new(streamWithFlush, bufferSize: 4);

// Write 4 bytes to fill the buffer
bufferedStream.WriteByte(1);
bufferedStream.WriteByte(2);
bufferedStream.WriteByte(3);
bufferedStream.WriteByte(4); // In .NET 9 and earlier, this caused an implicit flush

class StreamWithFlush : MemoryStream
{
    public override void Flush()
    {
        Console.WriteLine("Flush was called.");

        base.Flush();
    }
}

Module PreviousBehaviorExample
    Sub Example()
        Dim streamWithFlush As New StreamWithFlush()
        Dim bufferedStream As New BufferedStream(streamWithFlush, bufferSize:=4)

        ' Write 4 bytes to fill the buffer
        bufferedStream.WriteByte(1)
        bufferedStream.WriteByte(2)
        bufferedStream.WriteByte(3)
        bufferedStream.WriteByte(4) ' In .NET 9 and earlier, this caused an implicit flush
    End Sub

    Class StreamWithFlush
        Inherits MemoryStream

        Public Overrides Sub Flush()
            Console.WriteLine("Flush was called.")
            MyBase.Flush()
        End Sub
    End Class
End Module

New behavior

Starting in .NET 10, the WriteByte method no longer performs an implicit flush when the internal buffer is full. The buffer is only flushed when the BufferedStream.Flush() method is explicitly called or when the BufferedStream is disposed.

Type of breaking change

This change is a behavioral change.

Reason for change

The implicit flush behavior of BufferedStream.WriteByte(Byte) was inconsistent with other Write methods in the BufferedStream class, such as Write and WriteAsync. This inconsistency could lead to unexpected performance issues or unintended side effects when working with streams that are sensitive to flush operations. Removing the implicit flush ensures consistent behavior across all Write methods in BufferedStream.

If your application relies on the implicit flush behavior of BufferedStream.WriteByte, update your code to explicitly call the Flush method when needed. For example:

Before:

BufferedStream bufferedStream = new(new MemoryStream(), bufferSize: 4);
bufferedStream.WriteByte(1);
bufferedStream.WriteByte(2);
bufferedStream.WriteByte(3);
bufferedStream.WriteByte(4); // Implicit flush occurred here in .NET 9 and earlier

Dim bufferedStream As New BufferedStream(New MemoryStream(), bufferSize:=4)
bufferedStream.WriteByte(1)
bufferedStream.WriteByte(2)
bufferedStream.WriteByte(3)
bufferedStream.WriteByte(4) ' Implicit flush occurred here in .NET 9 and earlier

After:

BufferedStream bufferedStream = new(new MemoryStream(), bufferSize: 4);
bufferedStream.WriteByte(1);
bufferedStream.WriteByte(2);
bufferedStream.WriteByte(3);
bufferedStream.WriteByte(4);
bufferedStream.Flush(); // Explicit flush

Dim bufferedStream As New BufferedStream(New MemoryStream(), bufferSize:=4)
bufferedStream.WriteByte(1)
bufferedStream.WriteByte(2)
bufferedStream.WriteByte(3)
bufferedStream.WriteByte(4)
bufferedStream.Flush() ' Explicit flush

Affected APIs