diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 74902aa2876ed..4b4a310b63b10 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -28,7 +28,6 @@ See [Breaking changes in ASP.NET Core 10](/aspnet/core/breaking-changes/10/overv | [DateOnly and TimeOnly TryParse methods throw for invalid input](core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md) | Behavioral 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 | | [NamedPipeServerStream with PipeOptions.CurrentUserOnly tightens Unix socket file permissions](core-libraries/11/namedpipeserverstream-unix-permissions.md) | Behavioral change | | [Nullable.GetUnderlyingType throws for custom Type subclasses](core-libraries/11/nullable-getunderlyingtype-throws.md) | Behavioral change | | [API obsoletions with non-default diagnostic IDs (.NET 11)](core-libraries/11/obsolete-apis.md) | Source incompatible | @@ -54,7 +53,7 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | Title | Type of change | |-------|-------------------| | [IHost.RunAsync and IHost.StopAsync throw when a BackgroundService fails](extensions/11/ihost-runasync-stopasync-throw-backgroundservice-failure.md) | Behavioral change | -| [Some Microsoft.Extensions packages included in shared framework](extensions/11/extensions-in-shared-framework.md) | Behavioral change | +| [Some Microsoft.Extensions packages included in shared framework](extensions/11/extensions-in-shared-framework.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 deleted file mode 100644 index 7754b170ffd4e..0000000000000 --- a/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Breaking change: MemoryStream maximum capacity updated and exception behavior changed" -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 - -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 - -.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); // Threw 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 - -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 -bool TrySetLength(MemoryStream stream, long length) -{ - if (length > Array.MaxLength) - { - return false; - } - - stream.SetLength(length); - return true; -} -``` - -## Affected APIs - -- -- -- [MemoryStream constructor](xref:System.IO.MemoryStream.%23ctor) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index fd1c9c42fb72f..c3d38da80e05b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -18,8 +18,6 @@ items: 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 - href: core-libraries/11/memorystream-max-capacity.md - name: NamedPipeServerStream with PipeOptions.CurrentUserOnly tightens Unix socket file permissions href: core-libraries/11/namedpipeserverstream-unix-permissions.md - name: Nullable.GetUnderlyingType throws for custom Type subclasses @@ -42,7 +40,7 @@ items: items: - name: IHost.RunAsync and IHost.StopAsync throw when a BackgroundService fails href: extensions/11/ihost-runasync-stopasync-throw-backgroundservice-failure.md - - name: Some Microsoft.Extensions packages included in shared framework + - name: Some Microsoft.Extensions packages included in shared framework href: extensions/11/extensions-in-shared-framework.md - name: Globalization items: