From 34d993309dd49f9f4c9542deb617314a2d1d04d2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 8 Jan 2026 23:06:29 +0000 Subject: [PATCH 1/5] Initial plan From 1e9a0a0fbfd39280d3d627ed82144d59fd39c3ac Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 8 Jan 2026 23:12:48 +0000 Subject: [PATCH 2/5] Add MemoryStream maximum capacity breaking change documentation for .NET 11 Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/11.md | 1 + .../11/memorystream-max-capacity.md | 89 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 92 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 62c9c8cce0734..38e7062d947b6 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -19,6 +19,7 @@ If you're migrating an app to .NET 11, the breaking changes listed here might af | Title | Type of 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 | ## Globalization diff --git a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md new file mode 100644 index 0000000000000..5f2d9dc8ef9c2 --- /dev/null +++ b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md @@ -0,0 +1,89 @@ +--- +title: "Breaking change: MemoryStream maximum capacity updated and exception behavior changed" +description: "Learn about the breaking change in .NET 11 Preview 1 where MemoryStream enforces a maximum capacity and throws ArgumentOutOfRangeException for invalid capacity values." +ms.date: 01/08/2026 +ai-usage: ai-assisted +--- + +# MemoryStream maximum capacity updated and exception behavior changed + +Starting in .NET 11 Preview 1, the class enforces a maximum capacity of `0x7FFFFFC7` bytes, which is the actual maximum length of a byte array supported by the CLR. Additionally, the exception behavior has changed when attempting to set a `MemoryStream`'s capacity or length beyond this maximum. Instead of throwing an , the `MemoryStream` now throws an for invalid capacity or length values. + +## Version introduced + +.NET 11 Preview 1 + +## Previous behavior + +Previously, `MemoryStream` allowed capacities up to `int.MaxValue` (`0x7FFFFFFF`), which could result in an when attempting to allocate memory beyond the CLR's supported limit of `0x7FFFFFC7`. + +When setting the capacity or length of a `MemoryStream` to a value greater than the supported limit, an `OutOfMemoryException` was thrown. + +```csharp +var stream = new MemoryStream(); +stream.SetLength(int.MaxValue); // Throws OutOfMemoryException +``` + +## New behavior + +Starting in .NET 11, `MemoryStream` enforces a maximum capacity of `0x7FFFFFC7` bytes. Attempting to set the capacity or length beyond this limit throws an . + +The exception type for invalid capacity or length values has changed from `OutOfMemoryException` to `ArgumentOutOfRangeException`. + +```csharp +var stream = new MemoryStream(); +stream.SetLength(int.MaxValue); // Throws ArgumentOutOfRangeException +``` + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was introduced to align `MemoryStream`'s behavior with the actual memory allocation limits of the CLR. The previous behavior allowed developers to specify capacities or lengths that exceeded the supported limit, leading to runtime failures with less descriptive exceptions (`OutOfMemoryException`). By capping the maximum capacity and throwing `ArgumentOutOfRangeException`, the change improves runtime reliability and provides clearer feedback to developers. + +## Recommended action + +Developers should review any code that sets the capacity or length of a `MemoryStream` to ensure it doesn't exceed the maximum supported capacity. + +If your code was catching `OutOfMemoryException` when working with `MemoryStream` capacity or length operations, you should update it to also catch `ArgumentOutOfRangeException`, as both exceptions can still occur: + +- `ArgumentOutOfRangeException` is thrown when attempting to set an invalid capacity or length (exceeding the maximum). +- `OutOfMemoryException` can still be thrown if there's insufficient memory available on the machine. + +```csharp +var stream = new MemoryStream(); +try +{ + stream.SetLength(someLength); +} +catch (ArgumentOutOfRangeException) +{ + // Handle invalid capacity/length scenario +} +catch (OutOfMemoryException) +{ + // Handle out of memory scenario +} +``` + +You can also add a check before setting the capacity or length to avoid the exception: + +```csharp +var stream = new MemoryStream(); +long newLength = int.MaxValue; + +if (newLength > Array.MaxLength) +{ + throw new ArgumentOutOfRangeException(nameof(newLength), $"Length cannot exceed {Array.MaxLength} bytes."); +} + +stream.SetLength(newLength); +``` + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 7d17ec4e0fcd7..b0919f94fd835 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -12,6 +12,8 @@ items: items: - 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 + href: core-libraries/11/memorystream-max-capacity.md - name: Globalization items: - name: Japanese Calendar minimum supported date corrected From 75715be4b40afd76abd36f92d6f06dee14961f09 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 8 Jan 2026 17:38:37 -0800 Subject: [PATCH 3/5] Human edits --- .../core-libraries/11/memorystream-max-capacity.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md index 5f2d9dc8ef9c2..da2141d0c43c6 100644 --- a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md +++ b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md @@ -1,13 +1,13 @@ --- title: "Breaking change: MemoryStream maximum capacity updated and exception behavior changed" -description: "Learn about the breaking change in .NET 11 Preview 1 where MemoryStream enforces a maximum capacity and throws ArgumentOutOfRangeException for invalid capacity values." +description: "Learn about the breaking change in .NET 11 where MemoryStream enforces a maximum capacity and throws ArgumentOutOfRangeException for invalid capacity values." ms.date: 01/08/2026 ai-usage: ai-assisted --- # MemoryStream maximum capacity updated and exception behavior changed -Starting in .NET 11 Preview 1, the class enforces a maximum capacity of `0x7FFFFFC7` bytes, which is the actual maximum length of a byte array supported by the CLR. Additionally, the exception behavior has changed when attempting to set a `MemoryStream`'s capacity or length beyond this maximum. Instead of throwing an , the `MemoryStream` now throws an for invalid capacity or length values. +The class now enforces a maximum capacity of `0x7FFFFFC7` bytes, which is the actual maximum length of a byte array supported by the CLR. Additionally, the exception behavior has changed when attempting to set a `MemoryStream`'s capacity or length beyond this maximum. Instead of throwing an , the `MemoryStream` now throws an for invalid capacity or length values. ## Version introduced @@ -21,7 +21,7 @@ When setting the capacity or length of a `MemoryStream` to a value greater than ```csharp var stream = new MemoryStream(); -stream.SetLength(int.MaxValue); // Throws OutOfMemoryException +stream.SetLength(int.MaxValue); // Threw OutOfMemoryException. ``` ## New behavior @@ -45,7 +45,7 @@ This change was introduced to align `MemoryStream`'s behavior with the actual me ## Recommended action -Developers should review any code that sets the capacity or length of a `MemoryStream` to ensure it doesn't exceed the maximum supported capacity. +Review any code that sets the capacity or length of a `MemoryStream` to ensure it doesn't exceed the maximum supported capacity. If your code was catching `OutOfMemoryException` when working with `MemoryStream` capacity or length operations, you should update it to also catch `ArgumentOutOfRangeException`, as both exceptions can still occur: @@ -60,11 +60,11 @@ try } catch (ArgumentOutOfRangeException) { - // Handle invalid capacity/length scenario + // Handle invalid capacity/length scenario. } catch (OutOfMemoryException) { - // Handle out of memory scenario + // Handle out of memory scenario. } ``` @@ -86,4 +86,4 @@ stream.SetLength(newLength); - - -- +- [MemoryStream constructor](xref:System.IO.MemoryStream.%23ctor) From e56ad54fa2655830329734ca40e0aa11b8de06aa Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 8 Jan 2026 17:45:18 -0800 Subject: [PATCH 4/5] Update docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../core-libraries/11/memorystream-max-capacity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md index da2141d0c43c6..f20201465bb73 100644 --- a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md +++ b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md @@ -32,7 +32,7 @@ The exception type for invalid capacity or length values has changed from `OutOf ```csharp var stream = new MemoryStream(); -stream.SetLength(int.MaxValue); // Throws ArgumentOutOfRangeException +stream.SetLength(int.MaxValue); // Throws ArgumentOutOfRangeException. ``` ## Type of breaking change From 30f2e66526a44cf39e08698f849cd8d0329c4a5b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 9 Jan 2026 16:54:38 +0000 Subject: [PATCH 5/5] Update recommended action to use TrySetLength pattern instead of throwing same exception Co-authored-by: jozkee <16040868+jozkee@users.noreply.github.com> --- .../11/memorystream-max-capacity.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md index f20201465bb73..7754b170ffd4e 100644 --- a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md +++ b/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md @@ -71,15 +71,16 @@ catch (OutOfMemoryException) You can also add a check before setting the capacity or length to avoid the exception: ```csharp -var stream = new MemoryStream(); -long newLength = int.MaxValue; - -if (newLength > Array.MaxLength) +bool TrySetLength(MemoryStream stream, long length) { - throw new ArgumentOutOfRangeException(nameof(newLength), $"Length cannot exceed {Array.MaxLength} bytes."); + if (length > Array.MaxLength) + { + return false; + } + + stream.SetLength(length); + return true; } - -stream.SetLength(newLength); ``` ## Affected APIs