Document MemoryStream maximum capacity breaking change in .NET 11

[Copilot]

MemoryStream Breaking Change Documentation

• Create a new breaking change document for MemoryStream maximum capacity change
  • Create /home/runner/work/docs/docs/docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md
  • Follow the breaking change template structure
  • Address feedback from comments:
    • Use Array.MaxLength instead of hardcoding 0x7FFFFFC7
    • Clarify that both OutOfMemoryException and ArgumentOutOfRangeException can still occur
    • Update recommended action to reflect accurate guidance
• Update the index file /home/runner/work/docs/docs/docs/core/compatibility/11.md to include the new entry
• Update the TOC file /home/runner/work/docs/docs/docs/core/compatibility/toc.yml to include the new document
• Address PR feedback: Changed alternative recommendation from throwing exception to using TrySetLength pattern

Latest update: Changed the alternative code example to use a TrySetLength helper method that returns a boolean instead of throwing the same exception.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Update MemoryStream max capacity</issue_title>
<issue_description>### [Breaking change]: MemoryStream maximum capacity updated and exception behavior changed

Description

Starting in .NET 11 Preview 1, the System.IO.MemoryStream class has been updated to enforce a maximum capacity of 0x7FFFFFC7 bytes, which is the actual maximum length of a byte array supported by the CLR. Previously, MemoryStream allowed capacities up to int.MaxValue (0x7FFFFFFF), which could result in an OutOfMemoryException when attempting to allocate memory beyond the supported limit.

Additionally, the exception behavior has changed when attempting to set a MemoryStream's capacity or length beyond the new maximum. Instead of throwing an OutOfMemoryException, the MemoryStream now throws an ArgumentOutOfRangeException in these scenarios (this is the key difference).

This change ensures that MemoryStream behaves consistently with the CLR's actual memory allocation limits and provides a more accurate exception type for invalid capacity or length values.

Version

.NET 11 Preview 1

Previous behavior

• MemoryStream allowed capacities up to int.MaxValue (0x7FFFFFFF), which could result in an OutOfMemoryException 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.

Example:

var stream = new MemoryStream();
stream.SetLength(int.MaxValue); // Throws OutOfMemoryException

New behavior

• MemoryStream now enforces a maximum capacity of 0x7FFFFFC7 bytes. Attempting to set the capacity or length beyond this limit will throw an ArgumentOutOfRangeException.
• The exception type for invalid capacity or length values has changed from OutOfMemoryException to ArgumentOutOfRangeException.

Example:

var stream = new MemoryStream();
stream.SetLength(int.MaxValue); // Throws ArgumentOutOfRangeException

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 does not exceed the new maximum of 0x7FFFFFC7 bytes.

If your code was only catching OutOfMemoryException when working with MemoryStream capacity or length operations, you should update it to also catch ArgumentOutOfRangeException. For example:

var stream = new MemoryStream();
try
{
    stream.SetLength(someLength);
}
catch (OutOfMemoryException)
{
    // Handle out of memory scenario
}
catch (ArgumentOutOfRangeException)
{
    // Handle invalid capacity/length scenario
}

You can also add a check before setting the capacity or length to avoid the exception:

const int MaxMemoryStreamCapacity = Array.MaxLength;

var stream = new MemoryStream();
long newLength = int.MaxValue;

if (newLength > MaxMemoryStreamCapacity)
{
    throw new ArgumentOutOfRangeException(nameof(newLength), $"Length cannot exceed {MaxMemoryStreamCapacity} bytes.");
}

stream.SetLength(newLength);

Affected APIs

• System.IO.MemoryStream.Capacity
• System.IO.MemoryStream.SetLength(long)
• System.IO.MemoryStream.ctor(int)

Category

• Behavioral change: Existing binaries might behave differently at runtime.

---

Associated WorkItem - 543464</issue_description>

Comments on the Issue (you are @copilot in this section)

@jozkee > #### Recommended action > > ```csharp > var stream = new MemoryStream(); > try > { > stream.SetLength(someLength); > } > catch (OutOfMemoryException) > { > // Handle out of memory scenario > } > catch (ArgumentOutOfRangeException) > { > // Handle invalid capacity/length scenario > } > ```

@jkotas is it still possible that an OOMException arises from MemoryStream or can we safely suggest to fully replace it with ArgumentOutOfRangeException?</comment_new>
<comment_new>@jkotas

is it still possible that an OOMException arises from MemoryStream

What would make it impossible? new byte[....] can always throw an OutOfMemory exception if there is not enough memory available on the machine.

can we safely suggest to fully replace it with ArgumentOutOfRangeException

It de...

• Fixes [Breaking change]: Update MemoryStream max capacity #49545

---

✨ 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	docs/core/compatibility/11
docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md	docs/core/compatibility/core-libraries/11/memorystream-max-capacity
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

This PR documents a breaking change in .NET 11 Preview 1 where MemoryStream now enforces a maximum capacity of 0x7FFFFFC7 bytes and throws ArgumentOutOfRangeException instead of OutOfMemoryException for invalid capacity/length values.

Key changes:

• Created comprehensive breaking change documentation explaining the exception behavior change
• Updated TOC and index files for proper discoverability

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/core/compatibility/core-libraries/11/memorystream-max-capacity.md	New breaking change article documenting the MemoryStream maximum capacity enforcement and exception type change
docs/core/compatibility/toc.yml	Added TOC entry for the new breaking change article
docs/core/compatibility/11.md	Added index entry in the Core .NET libraries section

[BillWagner]

This LGTM @gewarren

Let's