Skip to content

Document breaking change: DeflateStream and GZipStream now encode empty payloads#51002

Merged
gewarren merged 6 commits intomainfrom
copilot/fix-empty-payload-encoding
Jan 12, 2026
Merged

Document breaking change: DeflateStream and GZipStream now encode empty payloads#51002
gewarren merged 6 commits intomainfrom
copilot/fix-empty-payload-encoding

Conversation

Copy link
Contributor

Copilot AI commented Jan 9, 2026 •
edited by github-actions bot
Loading

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)

✨ 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

Add breaking change article for DeflateStream and GZipStream empty pa…
22072ce 
…yload encoding

- Created breaking change article for .NET 11 Preview 1
- Updated 11.md index with new entry
- Updated toc.yml with new article link
- Added note to how-to-compress-and-extract-files.md referencing the breaking change

The article documents the behavioral change where DeflateStream and GZipStream
now always write headers and footers even for empty payloads, ensuring
properly formatted compressed streams.
Copilot AI changed the title [WIP] Fix DeflateStream and GZipStream encoding of empty payload Document breaking change: DeflateStream and GZipStream now encode empty payloads Jan 9, 2026
Copilot AI requested a review from gewarren January 9, 2026 18:40
@gewarren gewarren marked this pull request as ready for review January 9, 2026 19:24
@gewarren gewarren requested review from a team and adegeo as code owners January 9, 2026 19:24
@gewarren gewarren requested review from Copilot and rzikm January 9, 2026 19:24
Copilot AI reviewed Jan 9, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

rzikm
rzikm approved these changes Jan 12, 2026
View reviewed changes
Copy link
Member

@rzikm rzikm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

Copilot comments seem relevant.

BillWagner
BillWagner approved these changes Jan 12, 2026
View reviewed changes
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This LGTM.

Let's :shipit:

@gewarren gewarren enabled auto-merge (squash) January 12, 2026 16:34
@gewarren gewarren merged commit 7de8a4c into main Jan 12, 2026
11 checks passed
@gewarren gewarren deleted the copilot/fix-empty-payload-encoding branch January 12, 2026 16:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gewarren gewarren gewarren approved these changes

Copilot code review Copilot Copilot left review comments

@BillWagner BillWagner BillWagner approved these changes

@rzikm rzikm rzikm approved these changes

@adegeo adegeo Awaiting requested review from adegeo adegeo is a code owner

Assignees

@gewarren gewarren

Copilot code review Copilot

Labels

dotnet-fundamentals/svc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Breaking change]: DeflateStream and GZipStream encode empty payload into nonempty encoded payload.

5 participants

@BillWagner @gewarren @rzikm