Clarify File.WriteAllText and friends' truncation behaviour

[Smaug123]

Summary

Clarify in File.WriteAllText and friends that the files are truncated before being overwritten. The docs as stated do not define the result of overwriting hello world with bye: is it byelo world or bye?

I determined their actual behaviour empirically on aarch64-darwin on SDK 7.0.400 with File.WriteAllText : string * string -> unit and File.WriteAllBytes : string * byte[] -> unit, but have not actually checked the other overloads and methods; I have assumed that they are consistent with each other.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Summary

Clarify in File.WriteAllText and friends that the files are truncated before being overwritten. The docs as stated do not define the result of overwriting hello world with bye: is it byelo world or bye?

I determined their actual behaviour empirically on aarch64-darwin on SDK 7.0.400 with File.WriteAllText : string * string -> unit, but have not actually checked the other overloads and methods; I have assumed that they are consistent with each other.

Author:	Smaug123
Assignees:	-
Labels:	area-System.IO, community-contribution
Milestone:	-

[learn-build-service-prod]

Learn Build status updates of commit 27dc14f:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.IO/File.xml	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[bartonjs]

Stylistically, I'm torn between this being the right approach, or explaining it in terms of FileMode.Create (https://learn.microsoft.com/en-us/dotnet/api/system.io.filemode?view=net-7.0)

dotnet-api-docs/xml/System.IO/FileMode.xml

Line 178 in c1bd0b8

<summary>Specifies that the operating system should create a new file. If the file already exists, it will be overwritten. This requires <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" /> permission. <see langword="FileMode.Create" /> is equivalent to requesting that if the file does not exist, use <see cref="F:System.IO.FileMode.CreateNew" />; otherwise, use <see cref="F:System.IO.FileMode.Truncate" />. If the file already exists but is a hidden file, an <see cref="T:System.UnauthorizedAccessException" /> exception is thrown.</summary>

.

I also didn't look to see if all relevant places were updated. So, if this (vs explaining it in terms of FileMode.Create) is the preferred approach and it's complete, LGTM.

[Smaug123]

Personally I get the impression that since this is a high-level API, it shouldn't be described in terms of lower-level primitives; but that's an empirical question about the consistent style of the .NET docs which I'm not particularly well-placed to answer. (If I were writing the docs myself from scratch, I'd certainly say "This function is a high-level wrapper around the following lower-level calls", but my general vague impression is that the .NET docs don't do this.)

[jozkee]

Would you mind looking for other places that are appropriate to update. From a quick search of "overwrit" I found
Create, CreateText, Replace.

[gewarren]

Would you mind looking for other places that are appropriate to update. From a quick search of "overwrit" I found Create, CreateText, Replace.

Ping @Smaug123

[Smaug123]

I have now checked every use of the string "verwrit", and adjusted the ones where it seemed appropriate.

[learn-build-service-prod]

Learn Build status updates of commit 9672a7d:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.IO/File.xml	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[learn-build-service-prod]

Learn Build status updates of commit 94ad57e:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.IO/File.xml	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel