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

Author: Copilot

docs/core/compatibility/11.md

@@ -18,6 +18,7 @@ If you're migrating an app to .NET 11, the breaking changes listed here might af
 
 | Title                                                             | Type of change    |
 |-------------------------------------------------------------------|-------------------|
+| [DeflateStream and GZipStream write headers and footers for empty payload](core-libraries/11/deflatestream-gzipstream-empty-payload.md) | Behavioral change |
 | [Environment.TickCount made consistent with Windows timeout behavior](core-libraries/11/environment-tickcount-windows-behavior.md) | Behavioral change |
 | [MemoryStream maximum capacity updated and exception behavior changed](core-libraries/11/memorystream-max-capacity.md) | Behavioral change |
 | [TAR-reading APIs verify header checksums when reading](core-libraries/11/tar-checksum-validation.md) | Behavioral change |

docs/core/compatibility/core-libraries/11/deflatestream-gzipstream-empty-payload.md

@@ -0,0 +1,76 @@
+---
+title: "Breaking change: DeflateStream and GZipStream write headers and footers for empty payload"
+description: "Learn about the breaking change in .NET 11 where DeflateStream and GZipStream always write headers and footers to the output, even for empty payloads."
+ms.date: 01/09/2026
+ai-usage: ai-assisted
+---
+
+# DeflateStream and GZipStream write headers and footers for empty payload
+
+<xref:System.IO.Compression.DeflateStream> and <xref:System.IO.Compression.GZipStream> now always write format headers and footers to the output stream, even when no data is written. This ensures the output is a valid compressed stream according to the Deflate and GZip specifications.
+
+## Version introduced
+
+.NET 11 Preview 1
+
+## Previous behavior
+
+Previously, `DeflateStream` and `GZipStream` didn't produce any output if no data was written to the stream. This resulted in an empty output stream when compressing an empty input.
+
+```csharp
+using var output = new MemoryStream();
+using (var deflate = new DeflateStream(output, CompressionMode.Compress))
+{
+    // No data written.
+}
+Console.WriteLine(output.Length); // 0
+```
+
+## New behavior
+
+Starting in .NET 11, `DeflateStream` and `GZipStream` always write the appropriate headers and footers to the output stream, even when no data is written. This ensures the output contains valid compressed data according to the format specifications.
+
+```csharp
+using var output = new MemoryStream();
+using (var deflate = new DeflateStream(output, CompressionMode.Compress))
+{
+    // No data written.
+}
+Console.WriteLine(output.Length); // 2 (for Deflate) or 20 (for GZip).
+```
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Deflate and GZip compression formats include delimiters for the start and end of compressed data. The correct way to compress an empty payload with these formats includes only those delimiters. Some tools don't correctly react to empty content and always expect the compressed content to contain at least the appropriate header and footer. This change ensures compatibility with such tools and produces properly formatted compressed streams according to the specifications.
+
+## Recommended action
+
+If the previous behavior is desired, special-case empty content to not compress it via `DeflateStream` or `GZipStream`.
+
+```csharp
+byte[] dataToCompress = GetData();
+
+if (dataToCompress.Length == 0)
+{
+    // Don't compress empty data.
+    return Array.Empty<byte>();
+}
+
+using var output = new MemoryStream();
+using (var deflate = new DeflateStream(output, CompressionMode.Compress))
+{
+    deflate.Write(dataToCompress);
+}
+return output.ToArray();
+```
+
+If you need to distinguish between empty and nonempty compressed streams, track whether any data was written or check the original uncompressed data length before compression.
+
+## Affected APIs
+
+- <xref:System.IO.Compression.DeflateStream?displayProperty=fullName>
+- <xref:System.IO.Compression.GZipStream?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -10,6 +10,8 @@ items:
             href: 11.md
           - name: Core .NET libraries
             items:
+              - name: DeflateStream and GZipStream write headers and footers for empty payload
+                href: core-libraries/11/deflatestream-gzipstream-empty-payload.md
               - name: Environment.TickCount made consistent with Windows timeout behavior
                 href: core-libraries/11/environment-tickcount-windows-behavior.md
               - name: MemoryStream maximum capacity updated and exception behavior changed

docs/standard/io/how-to-compress-and-extract-files.md

@@ -3,10 +3,10 @@ title: "How to: Compress and extract files"
 description: Compress & extract files using System.IO.Compression. See examples using ZipFile, ZipArchive, ZipArchiveEntry, DeflateStream, & GZipStream.
 ms.date: "08/10/2022"
 ms.custom: devdivchpfy22
-dev_langs: 
+dev_langs:
   - "csharp"
   - "vb"
-helpviewer_keywords: 
+helpviewer_keywords:
   - "I/O [.NET], compression"
   - "compression"
   - "compress files"
@@ -69,9 +69,9 @@ You can also use the <xref:System.IO.Compression.GZipStream> and <xref:System.IO
 
 ## See also
 
-- <xref:System.IO.Compression.ZipArchive>  
-- <xref:System.IO.Compression.ZipFile>  
-- <xref:System.IO.Compression.ZipArchiveEntry>  
-- <xref:System.IO.Compression.DeflateStream>  
-- <xref:System.IO.Compression.GZipStream>  
+- <xref:System.IO.Compression.ZipArchive>
+- <xref:System.IO.Compression.ZipFile>
+- <xref:System.IO.Compression.ZipArchiveEntry>
+- <xref:System.IO.Compression.DeflateStream>
+- <xref:System.IO.Compression.GZipStream>
 - [File and stream I/O](index.md)