Document breaking change: DeflateStream and GZipStream now encode empty payloads

[Copilot]

In .NET 11 Preview 1, DeflateStream and GZipStream changed to always write compression headers and footers, even when no data is written. Previously, empty payloads produced no output.

Changes

• New article: docs/core/compatibility/core-libraries/11/deflatestream-gzipstream-empty-payload.md
  • Documents behavioral change with code examples
  • Provides migration guidance for scenarios requiring previous behavior
• Updated navigation: Added entry to TOC and 11.md index
• Cross-reference: Added note in how-to-compress-and-extract-files.md

Example

// Previous behavior: No output
using var ms = new MemoryStream();
using (var gzip = new GZipStream(ms, CompressionMode.Compress))
{
    // Write nothing
}
Console.WriteLine(ms.Length); // Was 0

// New behavior: Headers/footers written
using var ms = new MemoryStream();
using (var gzip = new GZipStream(ms, CompressionMode.Compress))
{
    // Write nothing
}
Console.WriteLine(ms.Length); // Now 20 (for GZip) or 2 (for Deflate)

Workaround for previous behavior: special-case empty content to skip compression.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: DeflateStream and GZipStream encode empty payload into nonempty encoded payload.</issue_title>
<issue_description>### Description

Deflate and GZip compression formats include delimiters for start and end of compressed data. The right way to compress empty payload with these formats includes only those delimiters.

Version

.NET 11 Preview 1

Previous behavior

DeflateStream and GZipStream would not produce any output if no data was written.

New behavior

DeflateStream and GZipStream always write headers and footers to the output.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Some tools do not correctly react to empty content and always expect the compressed content to contain at least the appropriate header and footer.

Recommended action

If previous behavior is desired, we recommend special casing empty content to not try to compress it via DeflateStream or GZipStream

Feature area

Core .NET libraries

Affected APIs

DeflateStream
GZipStream

---

Associated WorkItem - 543462</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Breaking change]: DeflateStream and GZipStream encode empty payload into nonempty encoded payload. #49393

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	Breaking changes in .NET 11
docs/core/compatibility/core-libraries/11/deflatestream-gzipstream-empty-payload.md	DeflateStream and GZipStream write headers and footers for empty payload
docs/core/compatibility/toc.yml	docs/core/compatibility/toc
docs/standard/io/how-to-compress-and-extract-files.md	How to: Compress and extract files

[Copilot]

Pull request overview

This PR documents a breaking change in .NET 11 Preview 1 where DeflateStream and GZipStream now always write compression headers and footers, even when no data is written. Previously, these streams produced no output for empty payloads.

• Creates comprehensive breaking change documentation with examples and migration guidance
• Updates navigation structure to include the new breaking change entry
• Includes whitespace cleanup in related documentation file

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/core/compatibility/core-libraries/11/deflatestream-gzipstream-empty-payload.md	New breaking change documentation describing the behavior change, including code examples and recommended actions
docs/core/compatibility/toc.yml	Adds TOC entry for the new breaking change article
docs/core/compatibility/11.md	Adds table entry linking to the new breaking change documentation
docs/standard/io/how-to-compress-and-extract-files.md	Whitespace cleanup (removes trailing spaces from YAML headers and links)

[Copilot]

The comment at line 39 contains inconsistent information. According to the PR description example, GZipStream should produce 20 bytes for an empty payload, not 10 bytes. The comment should be corrected to match the actual behavior.

Suggested change

	Console.WriteLine(output.Length); // 2 (for Deflate) or 10 (for GZip).
	Console.WriteLine(output.Length); // 2 (for Deflate) or 20 (for GZip).

[Copilot]

The phrase "special case" should be hyphenated when used as a verb. Change "special case empty content" to "special-case empty content".