Which Remarks apply to FileStream's four-argument constructor in the .NET 10 documentation?

Manica Moscon Advogados 5 Reputation points
2026-11-04T20:12:23.6566667+00:00

The .NET 10 API page documents the FileStream constructor taking String, FileMode, FileAccess, and FileShare. The parameter descriptions make access and sharing depend on the supplied arguments. The associated Remarks instead appear to describe fixed read/write access and read sharing.

The illustrative combination under consideration is new FileStream(path, FileMode.CreateNew, FileAccess.Write, FileShare.None); it has not been executed.

Do these Remarks govern this four-argument overload with explicit access/share values, or describe defaults for another overload? In particular, how should the Write/None combination be interpreted against that text?

Could you provide the official clarification or corrected reference applicable to .NET 10, preferably a versioned permalink where available, distinguishing a published contract from implementation evidence?

This is solely a documentation clarification request. No runtime behavior is being reported.

Developer technologies | .NET | Other
0 comments

2 answers

Sort by: Newest
Most helpful Newest Oldest
  1. Brian Pham (WICLOUD CORPORATION) 1,340 Reputation points Microsoft External Staff Moderator
    2026-11-05T03:31:57.3133333+00:00

    Hi @Manica Moscon Advogados ,

    The four-argument constructor explicitly accepts FileAccess and FileShare. Therefore, those supplied values determine the behavior of the resulting FileStream.

    For example:
new FileStream(
    path,
    FileMode.CreateNew,
    FileAccess.Write,
    FileShare.None);

    creates a new file, opens it for write access only, and does not allow sharing while the stream is open.

    The Remarks section states that FileShare.Read is the default only for constructors that do not expose a FileShare parameter. Since this overload does expose that parameter, the default does not apply.

    Based on the published API contract, the explicit FileAccess and FileShare arguments determine the behavior of this overload. However, the current Remarks text may be interpreted as applying more broadly than intended. If you believe the documentation is unclear or inconsistent, please use Open a documentation issue on the bottom of Learn page so that the .NET documentation team can review and clarify the wording.

    User's image

    If you found my response helpful or informative, I would greatly appreciate it if you could follow this guide for your confirmation.

    Thank you.

    Was this answer helpful?

    1 person found this answer helpful.

  2. AI answer

    2026-11-04T20:13:19.17+00:00

    The four-argument overload uses the supplied FileAccess and FileShare values, so FileAccess.Write/FileShare.None means a write-only, unshared stream; remarks describing fixed read/write access or FileShare.Read defaults do not override those explicit arguments.

    Published .NET 10 contract

    For:

    using FileStream stream = new(
    path,
    FileMode.CreateNew,
    FileAccess.Write,
    FileShare.None);

    the arguments mean:

    • FileMode.CreateNew: create a new file; throw IOException if the file already exists.^1^
    • FileAccess.Write: permit writing, but not reading. The FileAccess reference distinguishes Write from ReadWrite explicitly.^2^
    • FileShare.None: decline sharing while this handle remains open; other attempts to open the file fail until it is closed.^3^

    The constructor’s own summary likewise says that this overload initializes the stream with the specified creation mode, read/write permission, and sharing permission.^4^

    Consequently:

    • stream.CanWrite is expected to be true.
    • stream.CanRead is expected to be false.
    • A read operation through this stream is not enabled merely because a remark mentions read/write access.
    • FileShare.None is the requested sharing mode; it is not replaced with FileShare.Read.

    How to interpret the conflicting Remarks

    A default applies only when the caller has not supplied that setting. The constructor page itself contains the qualified statement:

    FileShare.Read is the default for those FileStream constructors without a FileShare parameter.

    That condition excludes the four-argument overload because it has an explicit share parameter.^4^

    Similarly, the FileStreamOptions.Share property defaults to FileShare.Read, but that is the default of the options property; it does not replace a FileShare argument passed directly to this constructor.^5^

    Microsoft’s .NET 10 File.OpenWrite documentation provides an especially direct cross-check: it says that File.OpenWrite(path) is equivalent to this exact four-argument overload with FileMode.OpenOrCreate, FileAccess.Write, and FileShare.None.^6^ Therefore, Write/None is an expressly documented and supported combination.

    Any overload-associated prose stating unconditionally that this constructor provides read/write access and read sharing is inconsistent with the overload summary, parameter definitions, enum contracts, and the documented File.OpenWrite equivalence. It should be treated as misplaced or over-broad documentation, not as a special rule that rewrites the arguments.

    Contract versus implementation evidence

    The published contract is the version-selected .NET 10 API documentation above. The page’s Source link pins the constructor to a specific repository commit:

    That implementation shows the four-argument constructor forwarding path, mode, access, and share unchanged to the fuller constructor, adding only default buffering/asynchronous settings. This is stable implementation evidence for the source snapshot linked from the .NET 10 page, but the Learn API descriptions remain the published contract.

    No separate official correction or documentation issue specifically correcting these four-argument Remarks appears in the available references. Until the page is corrected, the overload-specific parameter contract and the documented File.OpenWrite equivalence are the applicable official references.

    References

    1. FileMode Enum-Definition
    2. FileAccess Enum-Definition
    3. FileShare Enum-Definition
    4. FileStream Constructors-Definition
    5. FileStreamOptions.Share Property-Definition
    6. File.OpenWrite(String) Method-Definition
    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.