CompressionLevel validation breaking change (#27730)

Author: gewarren

docs/core/compatibility/7.0.md

@@ -0,0 +1,19 @@
+---
+title: Breaking changes in .NET 7
+description: Navigate to the breaking changes in .NET 7.
+ms.date: 01/04/2022
+no-loc: [Blazor, Razor, Kestrel]
+---
+# Breaking changes in .NET 7
+
+If you're migrating an app to .NET 7, the breaking changes listed here might affect you. Changes are grouped by technology area, such as ASP.NET Core or Windows Forms.
+
+> [!NOTE]
+>
+> This article is a work in progress. It's not a complete list of breaking changes in .NET 7. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet%2Fdocs%20or%20repo:aspnet%2FAnnouncements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%207%22%20or%20label:7.0.0)%20sort:created-desc).
+
+## Core .NET libraries
+
+| Title | Binary compatible | Source compatible | Introduced |
+| - | - | - | - |
+| [Validate CompressionLevel for BrotliStream](core-libraries/7.0/compressionlevel-validation.md) | ❌ | ✔️ | Preview 1 |

docs/core/compatibility/core-libraries/7.0/compressionlevel-validation.md

@@ -0,0 +1,44 @@
+---
+title: ".NET 7 breaking change: Validate CompressionLevel for BrotliStream"
+description: Learn about the .NET 7 breaking change in core .NET libraries where the CompressionLevel parameter to BrotliStream constructors is now validated.
+ms.date: 01/04/2022
+---
+# Validate CompressionLevel for BrotliStream
+
+The <xref:System.IO.Compression.CompressionLevel> argument that's passed to <xref:System.IO.Compression.BrotliStream> constructors is now validated to be one of the defined values of the enumeration.
+
+## Previous behavior
+
+Passing any value between 0 and 11 for the <xref:System.IO.Compression.CompressionLevel> parameter was considered valid. The value would either map to the one of the enumeration's defined values or passed as-is to the underlying Brotli implementation.
+
+## New behavior
+
+The only valid values for the <xref:System.IO.Compression.CompressionLevel> parameter of <xref:System.IO.Compression.BrotliStream> constructors are:
+
+- <xref:System.IO.Compression.CompressionLevel.Optimal?displayProperty=nameWithType>
+- <xref:System.IO.Compression.CompressionLevel.Fastest?displayProperty=nameWithType>
+- <xref:System.IO.Compression.CompressionLevel.NoCompression?displayProperty=nameWithType>
+- <xref:System.IO.Compression.CompressionLevel.SmallestSize?displayProperty=nameWithType>
+
+If you pass any other value, an <xref:System.ArgumentException> is thrown at run time.
+
+## Version introduced
+
+.NET 7 Preview 1
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility).
+
+## Reason for change
+
+Being able to pass arbitrary values that aren't defined by the <xref:System.IO.Compression.CompressionLevel> enumeration is unexpected and undocumented, and is likely to lead to mistakes.
+
+## Recommended action
+
+If necessary, change your code to pass in one of the valid <xref:System.IO.Compression.CompressionLevel> values.
+
+## Affected APIs
+
+- <xref:System.IO.Compression.BrotliStream.%23ctor(System.IO.Stream,System.IO.Compression.CompressionLevel,System.Boolean)>
+- <xref:System.IO.Compression.BrotliStream.%23ctor(System.IO.Stream,System.IO.Compression.CompressionLevel)>

docs/core/compatibility/toc.yml

@@ -19,6 +19,14 @@ items:
   - name: Breaking changes by version
     expanded: true
     items:
+    - name: .NET 7
+      items:
+      - name: Overview
+        href: 7.0.md
+      - name: Core .NET libraries
+        items:
+        - name: Default serialization format for TimeSpan
+          href: core-libraries/7.0/compressionlevel-validation.md
     - name: .NET 6
       items:
       - name: Overview
@@ -623,6 +631,10 @@ items:
           href: code-analysis/5.0/ca2247-ctor-arg-should-be-taskcreationoptions.md
     - name: Core .NET libraries
       items:
+      - name: .NET 7
+        items:
+        - name: Default serialization format for TimeSpan
+          href: core-libraries/7.0/compressionlevel-validation.md
       - name: .NET 6
         items:
         - name: API obsoletions with non-default diagnostic IDs