Remove .NET Framework remarks (System.IO)#12651
Open
gewarren wants to merge 1 commit into
Open
Conversation
Contributor
|
Tagging subscribers to this area: @dotnet/area-system-io |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR cleans up the .NET API reference docs by removing or rewriting .NET Framework-specific remarks, exceptions, and examples across System.IO and related namespaces, aligning the content with the post-split documentation layout.
Changes:
- Removes/rewrites remarks that referenced .NET Framework versions, app domains, CAS, and Windows Store app-specific guidance.
- Simplifies and modernizes async/I/O guidance in stream-related types and compression streams.
- Updates related links and exception descriptions to avoid framework-specific qualifiers.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.IO/Stream.xml | Updates async and Windows Runtime stream conversion remarks to remove .NET Framework-specific phrasing. |
| xml/System.IO/PathTooLongException.xml | Removes .NET Framework version gating from long-paths remarks. |
| xml/System.IO/Path.xml | Removes framework/version-specific path-validation notes and adjusts device-path wording. |
| xml/System.IO/InternalBufferOverflowException.xml | Rewords remarks to remove “.NET Framework” references in constructor guidance. |
| xml/System.IO/FileSystemInfo.xml | Simplifies exception descriptions to avoid framework-specific qualifiers. |
| xml/System.IO/FileSystemAclExtensions.xml | Updates remarks describing why these extension methods exist, removing “.NET Core” phrasing. |
| xml/System.IO/FileStream.xml | Removes framework/version-specific exception notes and streamlines async remarks. |
| xml/System.IO/FileInfo.xml | Removes framework/version-specific exception notes. |
| xml/System.IO/FileAttributes.xml | Removes “.NET Core” qualification from platform-support notes. |
| xml/System.IO/File.xml | Removes framework/version-specific exception notes and .NET Core-specific guidance in Encrypt/Decrypt remarks. |
| xml/System.IO/DirectoryInfo.xml | Updates Parent remarks to remove cross-framework behavioral notes. |
| xml/System.IO/Directory.xml | Removes framework/version-specific exception notes and updates Move behavior note. |
| xml/System.IO/BufferedStream.xml | Removes .NET Framework version notes from async legacy APIs and streamlines remarks. |
| xml/System.IO.Pipes/PipeStream.xml | Removes “.NET Framework” phrasing from the type-level remarks. |
| xml/System.IO.Packaging/PackageDigitalSignatureManager.xml | Removes “.NET Framework” phrasing from type-level remarks. |
| xml/System.IO.Packaging/Package.xml | Removes “.NET Framework” phrasing from type-level remarks. |
| xml/System.IO.MemoryMappedFiles/MemoryMappedFile.xml | Removes “.NET Core and .NET 5+ only” qualifiers from PNSE exception docs. |
| xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml | Removes .NET Framework-specific remarks and adjusts property docs. |
| xml/System.IO.Compression/GZipStream.xml | Simplifies zlib/async legacy remarks to remove .NET Framework references. |
| xml/System.IO.Compression/DeflateStream.xml | Simplifies zlib/async legacy remarks and removes .NET Framework references. |
| xml/System.IO.Compression/BrotliStream.xml | Updates async remarks to remove Windows Store app phrasing. |
| - On .NET Framework: All `Path` members that take a path as an argument throw an <xref:System.ArgumentException> if they detect invalid path characters. | ||
|
|
||
| - On .NET: <xref:System.IO.Path.GetFullPath*> is the only member that throws an <xref:System.ArgumentException> if the string contains invalid path characters. | ||
| <xref:System.IO.Path.GetFullPath*> validates the contents of a specified path string, and throw an <xref:System.ArgumentException> if the string contains characters that are not valid in path strings, as defined in the characters returned from the <xref:System.IO.Path.GetInvalidPathChars*> method. For example, on Windows-based desktop platforms, invalid path characters might include quote ("), less than (\<), greater than (>), pipe (|), backspace (\\b), null (\\0), and Unicode characters 16 through 18 and 20 through 25. |
| > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation. | ||
| > | ||
| > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows. | ||
| > Use of this API in is not recommended; it is included to enable portability for applications that move from .NET Framework but still explicitly target Windows. |
| ## Remarks | ||
|
|
||
| This extension method was added to .NET Core to bring the functionality that was provided by the `System.IO.Directory.CreateDirectory(System.String,System.Security.AccessControl.DirectorySecurity)` .NET Framework method. | ||
| This extension method was added to .NET provide the functionality of the `System.IO.Directory.CreateDirectory(System.String,System.Security.AccessControl.DirectorySecurity)` .NET Framework method. |
Comment on lines
+3229
to
3232
| This property returns a fully qualified path. | ||
|
|
||
| To ensure consistent behavior across versions and to make your intent explicit, retrieve the value of one of the following properties on the <xref:System.IO.DirectoryInfo> instance returned by `Parent`: | ||
|
|
|
|
||
| ]]></format> | ||
| </remarks> | ||
| <remarks>To be added.</remarks> |
Comment on lines
293
to
295
| ## Remarks | ||
| These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the <xref:System.IO.FileSystemWatcher.NotifyFilter*?displayProperty=nameWithType> and <xref:System.IO.FileSystemWatcher.IncludeSubdirectories*?displayProperty=nameWithType> properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the <xref:System.IO.FileSystemWatcher.InternalBufferSize?displayProperty=nameWithType> property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. | ||
| These constructors are used by the component to signify an error. Only use them if you're extending the class or .NET. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the <xref:System.IO.FileSystemWatcher.NotifyFilter*?displayProperty=nameWithType> and <xref:System.IO.FileSystemWatcher.IncludeSubdirectories*?displayProperty=nameWithType> properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the <xref:System.IO.FileSystemWatcher.InternalBufferSize?displayProperty=nameWithType> property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. | ||
|
|
| <format type="text/markdown"><![CDATA[ | ||
|
|
||
| This class represents the Deflate algorithm, which is an industry-standard algorithm for lossless file compression and decompression. Starting with .NET Framework 4.5, the <xref:System.IO.Compression.DeflateStream> class uses the zlib library. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of .NET Framework. | ||
| This class represents the Deflate algorithm, which is an industry-standard algorithm for lossless file compression and decompression. This class uses the zlib library for compression. |
| This class represents the gzip data format, which uses an industry-standard algorithm for lossless file compression and decompression. The format includes a cyclic redundancy check value for detecting data corruption. The gzip data format uses the same algorithm as the <xref:System.IO.Compression.DeflateStream> class, but can be extended to use other compression formats. The format can be readily implemented in a manner not covered by patents. | ||
|
|
||
| Starting with .NET Framework 4.5, the <xref:System.IO.Compression.DeflateStream> class uses the zlib library for compression. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of .NET Framework. | ||
| This class uses the zlib library for compression. |
Comment on lines
482
to
+485
| > [!IMPORTANT] | ||
| > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). | ||
| > This method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). | ||
|
|
||
| Starting with .NET Framework 4.5, you can perform asynchronous read operations by using the <xref:System.IO.Stream.ReadAsync*> method. The <xref:System.IO.Compression.DeflateStream.BeginRead*> method is still available in current versions to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). | ||
| This method is available to support legacy code; however, you can implement asynchronous I/O operations more easily by using the newer async methods such as <xref:System.IO.Stream.ReadAsync*>. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). |
|
|
||
| > [!NOTE] | ||
| > Starting with .NET Core 3.0, the `Move` method throws an <xref:System.IO.IOException> in all platforms when the `destDirName` already exists. See [C++ rename](https://linux.die.net/man/2/rename). | ||
| > The `Move` method throws an <xref:System.IO.IOException> in all platforms when the `destDirName` already exists. See [C++ rename](https://linux.die.net/man/2/rename). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
.NET Framework API ref has moved to its own repo (https://github.com/dotnet/dotnetfw-api-docs), so we can clean up .NET Framework remarks, exceptions, and code examples out of this repo. Contributes to #12513.
Removes remarks and examples related to:
Also remarks all remarks from obsolete APIs.
Hide whitespace changes