[Breaking change]: Remove implicit flush from BufferedStream.WriteByte

[adamsitnik]

Description

Starting in .NET 10 Preview 4, the BufferedStream.WriteByte method no longer performs an implicit flush when the internal buffer is full. This change was made to align the behavior of BufferedStream.WriteByte with other Write methods in the BufferedStream class, such as Write and WriteAsync, which do not perform an implicit flush.

Previously, when the internal buffer of a BufferedStream was full, calling WriteByte would automatically flush the buffer to the underlying stream. This behavior was inconsistent with other Write methods in BufferedStream, which do not perform an implicit flush under similar circumstances. The change ensures consistent behavior across all Write methods in BufferedStream.

This change addresses an issue where the implicit flush could lead to unexpected performance degradation or unintended side effects when working with streams that are sensitive to flush operations.

For more details, see the original pull request and the related GitHub issue.

Version

.NET 10 Preview 4

Previous behavior

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

Example

using System;
using System.IO;

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); // causes an implicit flush

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

        base.Flush();
    }
}

New behavior

The WriteByte method no longer performs an implicit flush when the internal buffer is full.

Type of breaking change

• Behavioral change: Existing binaries might behave differently at runtime.

Reason for change

The implicit flush behavior of BufferedStream.WriteByte 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.

Recommended action

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

Before

bufferedStream.WriteByte(1);
bufferedStream.WriteByte(2);
bufferedStream.WriteByte(3);
bufferedStream.WriteByte(4); // Implicit flush occurs here

After

bufferedStream.WriteByte(1);
bufferedStream.WriteByte(2);
bufferedStream.WriteByte(3);
bufferedStream.WriteByte(4);
bufferedStream.Flush(); // Explicit flush

Affected APIs

• System.IO.BufferedStream.WriteByte

Additional information

This change was introduced in .NET 10 Preview 4. For more details, see the pull request and the related issue.