Reorganize includes folder#12757
Draft
gewarren wants to merge 6 commits into
Draft
Conversation
Contributor
|
Tagging subscribers to this area: @dotnet/area-system-io-compression |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR contributes to dotnet/dotnet-api-docs issue #12513 by reorganizing reusable markdown content under includes/ and updating API XML docs to reference the reorganized includes (or inline the content), reducing reliance on the old includes/remarks/... layout.
Changes:
- Updated multiple XML docs to reference new include paths in
~/includes/*.md(and in several cases inlined previously-included remarks content directly into the XML). - Added new include fragments for
String.Format,WaitHandle exitContext, andPictureBoxremote-image load behavior. - Deleted a set of old include markdown files (primarily under
includes/remarks/System.IO.Compression/...) that are no longer referenced.
Reviewed changes
Copilot reviewed 23 out of 27 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System/String.xml | Updates provider-string-format include path to the reorganized includes/ root. |
| xml/System.Windows.Forms/PictureBox.xml | Updates include path for the “Load behavior changes” content. |
| xml/System.Threading/WaitHandle.xml | Updates include path for “Exit the context” content to a new root include. |
| xml/System.IO.Compression/ZipFileExtensions.xml | Replaces an include with inlined remarks content. |
| xml/System.IO.Compression/ZipFile.xml | Replaces includes with inlined remarks content for type and Open method. |
| xml/System.IO.Compression/ZipArchiveMode.xml | Replaces an include with inlined remarks content. |
| xml/System.IO.Compression/ZipArchiveEntry.xml | Replaces several includes with inlined remarks content. |
| xml/System.IO.Compression/ZipArchive.xml | Replaces includes with inlined remarks content (type + ctor remarks). |
| xml/System.IO.Compression/DeflateStream.xml | Replaces ctor remarks includes with inlined content and snippet references. |
| xml/System.IO.Compression/CompressionLevel.xml | Replaces an include with inlined remarks content. |
| includes/waithandle-exit-context.md | New include fragment for exitContext behavior explanation. |
| includes/simple-string-format.md | New include fragment intended for String.Format guidance. |
| includes/provider-string-format.md | New include fragment for provider-based String.Format guidance. |
| includes/picturebox-load-behavior-changes.md | New include fragment documenting .NET 8 PictureBox remote load behavior change. |
| includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipFile/ZipFile.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipFile/Open.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchiveMode/ZipArchiveMode.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchiveEntry/Name.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchiveEntry/LastWriteTime.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchiveEntry/FullName.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchive/ZipArchive.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/ZipArchive/.ctor_Stream_ZipArchiveMode_Boolean_Encoding.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionMode.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/DeflateStream/.ctor_Stream_CompressionLevel.md | Deleted (content moved/inlined). |
| includes/remarks/System.IO.Compression/CompressionLevel/CompressionLevel.md | Deleted (content moved/inlined). |
Comment on lines
+57
to
+58
| > [!NOTE] | ||
| > To use the <xref:System.IO.Compression.ZipFile> class in a .NET Framework app, you must add a reference to the `System.IO.Compression.FileSystem` assembly in your project. For information on how to add a reference to your project in Visual Studio, see [How to: Add or Remove References](/visualstudio/ide/how-to-add-or-remove-references-by-using-the-reference-manager). |
|
|
||
| When you create a new entry, the file is compressed and added to the zip package. The <xref:System.IO.Compression.ZipArchive.CreateEntry*> method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. | ||
|
|
||
| If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the <xref:System.IO.Compression.ZipFileExtensions> class) for the <xref:System.IO.Compression.ZipArchive> class: <xref:System.IO.Compression.ZipFileExtensions.CreateEntryFromFile(System.IO.Compression.ZipArchive,System.String,System.String)>, <xref:System.IO.Compression.ZipFileExtensions.CreateEntryFromFile(System.IO.Compression.ZipArchive,System.String,System.String,System.IO.Compression.CompressionLevel)>, <xref:System.IO.Compression.ZipFileExtensions.ExtractToDirectory(System.IO.Compression.ZipArchive,System.String)>, and <xref:System.IO.Compression.ZipFileExtensions.ExtractToDirectory(System.IO.Compression.ZipArchive,System.String,System.Boolean)> (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the <xref:System.IO.Compression.DeflateStream> or <xref:System.IO.Compression.GZipStream> class, or you can use the Windows Runtime types <xref:Windows.Storage.Compression.Compressor> and <xref:Windows.Storage.Compression.Decompressor>. |
| :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/Entries/program1.cs" id="Snippet1"::: | ||
| :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/Entries/program1.vb" id="Snippet1"::: | ||
|
|
||
| The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. |
| [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipFileExtensions/ZipFileExtensions.md)] | ||
| The <xref:System.IO.Compression.ZipFileExtensions> class contains only static methods that extend the <xref:System.IO.Compression.ZipArchive> and <xref:System.IO.Compression.ZipArchiveEntry> classes. You do not create an instance of the <xref:System.IO.Compression.ZipFileExtensions> class; instead, you use these methods from instances of <xref:System.IO.Compression.ZipArchive> or <xref:System.IO.Compression.ZipArchiveEntry>. | ||
|
|
||
| To use the extension methods, you must reference the `System.IO.Compression.FileSystem` assembly in your project. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8.x Store apps. Therefore, the <xref:System.IO.Compression.ZipFileExtensions> and <xref:System.IO.Compression.ZipFile> classes (both of which are in the `System.IO.Compression.FileSystem` assembly) are not available in Windows 8.x Store apps. In Windows 8.x Store apps, you work with compressed files by using the methods in <xref:System.IO.Compression.ZipArchive>, <xref:System.IO.Compression.ZipArchiveEntry>, <xref:System.IO.Compression.DeflateStream>, and <xref:System.IO.Compression.GZipStream>. |
| [!INCLUDE[remarks](~/includes/remarks/System.IO.Compression/ZipArchiveEntry/ZipArchiveEntry.md)] | ||
| A zip archive contains an entry for each compressed file. The <xref:System.IO.Compression.ZipArchiveEntry> class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. | ||
|
|
||
| The methods for manipulating zip archives and their file entries are spread across three classes: <xref:System.IO.Compression.ZipFile>, <xref:System.IO.Compression.ZipArchive> and <xref:System.IO.Compression.ZipArchiveEntry>. |
| :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/CreateEntry/program1.cs" id="Snippet1"::: | ||
| :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/CreateEntry/program1.vb" id="Snippet1"::: | ||
|
|
||
| The second example shows how to use the <xref:System.IO.Compression.ZipFileExtensions.ExtractToFile(System.IO.Compression.ZipArchiveEntry,System.String)> extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. |
| <format type="text/markdown"><] | ||
| The <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the <xref:System.IO.Compression.ZipArchiveEntry.Name*> property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the <xref:System.IO.Compression.ZipFileExtensions.CreateEntryFromFile*> method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.Name*> property. The first entry will also have `NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property, but the second entry will have `AddedFolder\\NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property. |
| <format type="text/markdown"><] | ||
| The <xref:System.IO.Compression.ZipArchiveEntry.Name*> property contains the portion of the <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the <xref:System.IO.Compression.ZipFileExtensions.CreateEntryFromFile*> method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.Name*> property. The first entry will also have `NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property, but the second entry will have `AddedFolder\\NewEntry.txt` in the <xref:System.IO.Compression.ZipArchiveEntry.FullName*> property. |
|
|
||
| When you set the `mode` parameter to <xref:System.IO.Compression.ZipArchiveMode.Create>, the archive is opened with <xref:System.IO.FileMode.CreateNew?displayProperty=nameWithType> as the file mode value. If the archive already exists, an <xref:System.IO.IOException> is thrown. | ||
|
|
||
| When you set the `mode` parameter to <xref:System.IO.Compression.ZipArchiveMode.Update>, the archive is opened with <xref:System.IO.FileMode.OpenOrCreate?displayProperty=nameWithType> as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in <xref:System.IO.Compression.ZipArchiveMode.Update> mode is not as efficient as creating it in <xref:System.IO.Compression.ZipArchiveMode.Create> mode. |
| This method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to convert the value of an expression to its string representation and to embed that representation in a string. In performing the conversion, the method uses culture-sensitive formatting or a custom formatter. The method converts `arg0` to its string representation by calling its **ToString(IFormatProvider)** method or, if the object's corresponding format item includes a format string, by calling its **ToString(String,IFormatProvider)** method. If these methods don't exist, it calls the object's parameterless **ToString** method. | ||
|
|
||
| [!INCLUDE[provider-string-format](~/includes/remarks/System/String/provider-string-format.md)] | ||
| [!INCLUDE[provider-string-format](~/includes/provider-string-format.md)] |
gewarren
commented
Jun 18, 2026
|
|
||
| ```xml | ||
| <Item>Test with an entity: 123</Item><Item>Test with a child element <more> stuff</Item><Item>Test with a CDATA section <![CDATA[<456>]]> def</Item><Item>Test with a char entity: A</Item><!-- Fourteen chars in this element.--><Item>1234567890ABCD</Item></Items> | ||
| <Item>Test with an entity: 123</Item><Item>Test with a child element <more> stuff</Item><Item>Test with a CDATA section %3C![CDATA[<456>]]%3E def</Item><Item>Test with a char entity: A</Item><!-- Fourteen chars in this element.--><Item>1234567890ABCD</Item></Items> |
Collaborator
Author
There was a problem hiding this comment.
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.
Contributes to #12513.