Add breaking change documentation for BufferedStream.WriteByte implicit flush removal in .NET 10

[Copilot]

Summary

This PR adds documentation for a breaking change in .NET 10 Preview 4 where BufferedStream.WriteByte no longer performs an implicit flush when the internal buffer is full.

Changes

• New documentation file: docs/core/compatibility/core-libraries/10.0/bufferedstream-writebyte-flush.md

  • Describes the behavioral change introduced in .NET 10 Preview 4
  • Explains the previous behavior where WriteByte would automatically flush the buffer
  • Documents the new consistent behavior across all Write methods
  • Provides recommended migration actions with code examples

• Code snippets: Created compilable C# and Visual Basic examples demonstrating:

  • The previous implicit flush behavior
  • Migration from implicit to explicit flush calls
  • Located in snippets/bufferedstream-writebyte-flush/csharp/ and snippets/bufferedstream-writebyte-flush/vb/

• TOC and index updates:

  • Added entry to toc.yml under Core .NET libraries (alphabetically ordered)
  • Updated 10.0.md index with the breaking change entry

Context

This change aligns BufferedStream.WriteByte behavior with other Write methods in the BufferedStream class (Write and WriteAsync), which don't perform implicit flushes. The inconsistency could lead to unexpected performance issues or unintended side effects when working with streams sensitive to flush operations.

Fixes #496356

References

• Original PR in dotnet/runtime
• Related issue in dotnet/runtime

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Remove implicit flush from BufferedStream.WriteByte</issue_title>
<issue_description>### 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.

---

Associated WorkItem - 496356</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #48913

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/10.0.md	Breaking changes in .NET 10
docs/core/compatibility/core-libraries/10.0/bufferedstream-writebyte-flush.md	BufferedStream.WriteByte no longer performs implicit flush
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull Request Overview

This PR documents a breaking change in .NET 10 Preview 4 where BufferedStream.WriteByte no longer performs an implicit flush when the internal buffer is full, aligning its behavior with other Write methods in the BufferedStream class.

Key changes:

• Added comprehensive breaking change documentation explaining the behavioral change and migration guidance
• Created compilable code snippets in both C# and Visual Basic demonstrating the previous behavior and migration path
• Updated the table of contents and index to include the new breaking change entry

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/core/compatibility/core-libraries/10.0/bufferedstream-writebyte-flush.md	Main documentation file describing the breaking change, previous/new behavior, and migration guidance
docs/core/compatibility/core-libraries/10.0/snippets/bufferedstream-writebyte-flush/csharp/Program.cs	C# code examples demonstrating the behavioral change and recommended migration
docs/core/compatibility/core-libraries/10.0/snippets/bufferedstream-writebyte-flush/csharp/BufferedStreamWriteByteFlush.csproj	Project file for C# code snippets
docs/core/compatibility/core-libraries/10.0/snippets/bufferedstream-writebyte-flush/vb/Program.vb	Visual Basic code examples demonstrating the behavioral change and recommended migration
docs/core/compatibility/core-libraries/10.0/snippets/bufferedstream-writebyte-flush/vb/BufferedStreamWriteByteFlush.vbproj	Project file for Visual Basic code snippets
docs/core/compatibility/toc.yml	Added TOC entry for the breaking change under Core .NET libraries
docs/core/compatibility/10.0.md	Added index table entry for the breaking change

[BillWagner]

After updating to .NET 10, this looks great.