Correct FileStream(FileOptions) docs for bufferSize = 0 behavior

[Copilot]

The docs for FileStream(string, FileMode, FileAccess, FileShare, int, FileOptions) currently state that bufferSize must be > 0 and that 0 throws. Runtime behavior allows 0 and only rejects negative values.

• Scope: targeted constructor docs

  • Updated the bufferSize parameter text for the (..., int bufferSize, FileOptions options) overload to allow non-negative values.
  • Documented that bufferSize: 0 disables internal buffering.

• Exception contract alignment

  • Updated ArgumentOutOfRangeException text for the same overload from “negative or zero” to “negative”.

• Result

  • Documentation now matches .NET 10 runtime semantics for this overload without changing unrelated constructor entries.

<!-- before -->
<param name="bufferSize">... greater than 0 ...</param>
<exception cref="T:System.ArgumentOutOfRangeException">
  <paramref name="bufferSize" /> is negative or zero.
</exception>

<!-- after -->
<param name="bufferSize">... non-negative ... A value of 0 disables buffering ...</param>
<exception cref="T:System.ArgumentOutOfRangeException">
  <paramref name="bufferSize" /> is negative.
</exception>

• Fixes FileStream constructor documentation incorrectly states that bufferSize: 0 throws #13060

---

Internal previews

File	Preview link
xml/System.IO/FileStream.xml	Learn preview

Build report

[adamsitnik]

@copilot Passing 1 as bufferSize works on every .NET version, but 0 only in .NET 6 and above. Please do capture that in the doc.

[Copilot]

@copilot Passing 1 as bufferSize works on every .NET version, but 0 only in .NET 6 and above. Please do capture that in the doc.

Updated in cc63e7a. The constructor docs now state that bufferSize = 0 is supported in .NET 6 and later (disables buffering), and that 0 throws in versions earlier than .NET 6.

[adamsitnik]

@copilot please address my feedback

[Copilot]

@copilot please address my feedback

Addressed in 5abebd3.

[adamsitnik]

LGTM!

[Copilot]

🟡 Changes recommended

The updated bufferSize parameter text is potentially misleading for pre-.NET 6 readers because it opens with “non-negative” while the exception contract still disallows 0 in those versions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the API reference documentation for FileStream(string, FileMode, FileAccess, FileShare, int bufferSize, FileOptions options) so the bufferSize parameter and related ArgumentOutOfRangeException text better match runtime behavior (notably for bufferSize == 0).

Changes:

• Updates the bufferSize parameter description to reflect non-negative values and document buffering behavior for 0/1.
• Refines the ArgumentOutOfRangeException contract to distinguish negative values from the pre-.NET 6 behavior for bufferSize == 0.

File summaries

File	Description
xml/System.IO/FileStream.xml	Adjusts constructor parameter and exception documentation for bufferSize to align with runtime semantics and version differences.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[gewarren]

We actually removed all comments for out of support versions. When you say versions earlier than .NET 6, does that apply to .NET Framework as well? If so, let's put that info in the dotnetfw-api-docs repo instead and just state the [.NET 6+] behavior here without a version.