diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 1e880ac7f620e..2b6f0d9fde023 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -121,6 +121,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 | | [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 | | [StatusStrip uses System RenderMode by default](windows-forms/10.0/statusstrip-renderer.md) | Behavioral change | Preview 1 | +| [System.Drawing OutOfMemoryException changed to ExternalException](windows-forms/10.0/system-drawing-outofmemory-externalexception.md) | Behavioral change | Preview 5 | ## Windows Presentation Foundation (WPF) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 17681c3d90a0b..399f012307a0e 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -136,6 +136,8 @@ items: href: windows-forms/10.0/treeview-text-location.md - name: StatusStrip uses System RenderMode by default href: windows-forms/10.0/statusstrip-renderer.md + - name: System.Drawing OutOfMemoryException changed to ExternalException + href: windows-forms/10.0/system-drawing-outofmemory-externalexception.md - name: WPF items: - name: Incorrect usage of DynamicResource causes application crash diff --git a/docs/core/compatibility/windows-forms/10.0/system-drawing-outofmemory-externalexception.md b/docs/core/compatibility/windows-forms/10.0/system-drawing-outofmemory-externalexception.md new file mode 100644 index 0000000000000..8c1049f6bee74 --- /dev/null +++ b/docs/core/compatibility/windows-forms/10.0/system-drawing-outofmemory-externalexception.md @@ -0,0 +1,74 @@ +--- +title: "Breaking change: System.Drawing OutOfMemoryException changed to ExternalException" +description: "Learn about the breaking change in .NET 10 where System.Drawing GDI+ OutOfMemory errors now throw ExternalException instead of OutOfMemoryException." +ms.date: 08/15/2025 +ai-usage: ai-assisted +dev_langs: +- CSharp +- VB +--- + +# System.Drawing OutOfMemoryException changed to ExternalException + +GDI+ error handling in System.Drawing has been updated to throw instead of for `Status.OutOfMemory` errors. + +## Version introduced + +.NET 10 Preview 5 + +## Previous behavior + +When GDI+ encountered `Status.OutOfMemory` errors (often due to invalid input rather than actual memory issues), System.Drawing APIs threw . + +## New behavior + +Starting in .NET 10, when GDI+ encounters `Status.OutOfMemory` errors, System.Drawing APIs now throw . + +## Type of breaking change + +This is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +GDI+ isn't particularly good at returning errors when it's unable to create internal objects. There are many cases where object creation fails due to invalid input, and higher-level code gets a null and turns it into `Status.OutOfMemory`. This is frequently a source of confusion since the error is often not related to actual memory issues. + +The change to `ExternalException` provides more accurate error reporting, as this exception type is already thrown in other System.Drawing code paths for similar GDI+ errors. + +## Recommended action + +If your code catches `OutOfMemoryException` when using System.Drawing APIs, ensure you also catch `ExternalException` to handle these GDI+ errors. + +```csharp +try +{ + // System.Drawing operations +} +catch (ExternalException ex) +{ + // Handle GDI+ errors (including former OutOfMemoryException cases) +} +catch (OutOfMemoryException ex) +{ + // Handle actual memory issues +} +``` + +```vb +Try + ' System.Drawing operations +Catch ex As ExternalException + ' Handle GDI+ errors (including former OutOfMemoryException cases) +Catch ex As OutOfMemoryException + ' Handle actual memory issues +End Try +``` + +## Affected APIs + +All System.Drawing APIs that interact with GDI+ and previously could throw `OutOfMemoryException` for `Status.OutOfMemory` errors, including but not limited to: + +- constructors and methods +- methods +- methods +- constructors and methods +- Other System.Drawing types that use GDI+ internally