dotnet · gewarren · Feb 14, 2023 · Feb 1, 2023 · Feb 1, 2023 · Feb 1, 2023
@@ -48,8 +48,12 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 
 ## Windows Forms
 
-| Title                                                                                                 | Type of change      | Introduced |
-| ----------------------------------------------------------------------------------------------------- | ------------------- | ---------- |
-| [Anchor layout changes](windows-forms/8.0/anchor-layout.md)                                           | Behavioral change   | Preview 1  |
-| [Top-level forms scale minimum and maximum size to DPI](windows-forms/8.0/forms-scale-size-to-dpi.md) | Behavioral change   | Preview 1  |
-| [WFDEV002 obsoletion is now an error](windows-forms/8.0/domainupdownaccessibleobject.md)              | Source incompatible | Preview 1  |
+| Title                                                                                                  | Type of change      | Introduced |
+| ------------------------------------------------------------------------------------------------------ | ------------------- | ---------- |
+| [Anchor layout changes](windows-forms/8.0/anchor-layout.md)                                            | Behavioral change   | Preview 1  |
+| [ExceptionCollection ctor throws ArgumentException](windows-forms/8.0/exceptioncollection.md)          | Behavioral change   | Preview 1  |
+| [Forms scale according to AutoScaleMode](windows-forms/8.0/top-level-window-scaling.md)                | Behavioral change   | Preview 1  |
+| [ImageList.ColorDepth default is Depth32Bit](windows-forms/8.0/imagelist-colordepth.md)                | Behavioral change   | Preview 1  |
+| [TableLayoutStyleCollection throws ArgumentException](windows-forms/8.0/tablelayoutstylecollection.md) | Behavioral change   | Preview 1  |
+| [Top-level forms scale minimum and maximum size to DPI](windows-forms/8.0/forms-scale-size-to-dpi.md)  | Behavioral change   | Preview 1  |
+| [WFDEV002 obsoletion is now an error](windows-forms/8.0/domainupdownaccessibleobject.md)               | Source incompatible | Preview 1  |
@@ -42,6 +42,14 @@ items:
       items:
       - name: Anchor layout changes
         href: windows-forms/8.0/anchor-layout.md
+      - name: ExceptionCollection ctor throws ArgumentException
+        href: windows-forms/8.0/exceptioncollection.md
+      - name: Forms scale according to AutoScaleMode
+        href: windows-forms/8.0/top-level-window-scaling.md
+      - name: ImageList.ColorDepth default is Depth32Bit
+        href: windows-forms/8.0/imagelist-colordepth.md
+      - name: TableLayoutStyleCollection throws ArgumentException
+        href: windows-forms/8.0/tablelayoutstylecollection.md
       - name: Top-level forms scale size to DPI
         href: windows-forms/8.0/forms-scale-size-to-dpi.md
       - name: WFDEV002 obsoletion is now an error
@@ -1378,6 +1386,14 @@ items:
       items:
       - name: Anchor layout changes
         href: windows-forms/8.0/anchor-layout.md
+      - name: ExceptionCollection ctor throws ArgumentException
+        href: windows-forms/8.0/exceptioncollection.md
+      - name: Forms scale according to AutoScaleMode
+        href: windows-forms/8.0/top-level-window-scaling.md
+      - name: ImageList.ColorDepth default is Depth32Bit
+        href: windows-forms/8.0/imagelist-colordepth.md
+      - name: TableLayoutStyleCollection throws ArgumentException
+        href: windows-forms/8.0/tablelayoutstylecollection.md
       - name: Top-level forms scale size to DPI
         href: windows-forms/8.0/forms-scale-size-to-dpi.md
       - name: WFDEV002 obsoletion is now an error

@@ -0,0 +1,36 @@
+---
+title: "Breaking change: ExceptionCollection constructor throws ArgumentException"
+description: Learn about the breaking change in .NET 8 for Windows Forms where the ExceptionCollection constructor now throws an exception if the input is not of type Exception.
+ms.date: 02/06/2023
+---
+# ExceptionCollection ctor throws ArgumentException
+
+The <xref:System.ComponentModel.Design.ExceptionCollection> constructor now throws an <xref:System.ArgumentException> if the elements in the input array are not of type <xref:System.Exception>.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+Previously, the <xref:System.ComponentModel.Design.ExceptionCollection> constructor did not check the type passed in, which could delay failure until later in the process. No exceptions were thrown during object creation.
+
+## New behavior
+
+Starting in .NET 8, if the elements in the input array are not of type <xref:System.Exception>, an <xref:System.ArgumentException> is thrown.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change helps to make exception types consistent across the code base.
+
+## Recommended action
+
+For most scenarios, this change should not have a significant impact. However, consider updating your code to handle <xref:System.ArgumentException> at constructor call sites.
+
+## Affected APIs
+
+- <xref:System.ComponentModel.Design.ExceptionCollection.%23ctor(System.Collections.ArrayList)> constructor
@@ -62,3 +62,7 @@ If the new behavior is problematic for you, you can opt out by setting `System.W
 ## Affected APIs
 
 N/A
+
+## See also
+
+- [Forms scale according to AutoScaleMode](top-level-window-scaling.md)
@@ -0,0 +1,36 @@
+---
+title: "Breaking change: ImageList.ColorDepth default is Depth32Bit"
+description: Learn about the breaking change in .NET 8 for Windows Forms where the default value of ImageList.ColorDepth has changed from Depth8Bit to Depth32Bit.
+ms.date: 01/31/2023
+---
+# ImageList.ColorDepth default is Depth32Bit
+
+The default value for <xref:System.Windows.Forms.ImageList.ColorDepth?displayProperty=nameWithType> has changed over time. Starting in .NET 8, the default value has changed from <xref:System.Windows.Forms.ColorDepth.Depth8Bit> to <xref:System.Windows.Forms.ColorDepth.Depth32Bit>. This change affects both new and existing applications if they're upgraded to target .NET 8.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+The default value for <xref:System.Windows.Forms.ImageList.ColorDepth?displayProperty=nameWithType> was <xref:System.Windows.Forms.ColorDepth.Depth8Bit?displayProperty=nameWithType>.
+
+## New behavior
+
+If you haven't explicitly set <xref:System.Windows.Forms.ImageList.ColorDepth?displayProperty=nameWithType> for an image list, the color depth will automatically be reset to <xref:System.Windows.Forms.ColorDepth.Depth32Bit?displayProperty=nameWithType>. This could increase your app's memory usage.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The default value was changed to improve image quality.
+
+## Recommended action
+
+If you want to continue using the previous color depth, explicitly set <xref:System.Windows.Forms.ImageList.ColorDepth?displayProperty=nameWithType> to <xref:System.Windows.Forms.ColorDepth.Depth8Bit?displayProperty=nameWithType>.
+
+## Affected APIs
+
+- <xref:System.Windows.Forms.ImageList.ColorDepth?displayProperty=fullName>
@@ -0,0 +1,38 @@
+---
+title: "Breaking change: TableLayoutStyleCollection throws ArgumentException"
+description: Learn about the breaking change in .NET 8 for Windows Forms where inserting or removing an object that's not a TableLayoutStyle throws an exception.
+ms.date: 02/06/2023
+---
+# TableLayoutStyleCollection throws ArgumentException
+
+<xref:System.Windows.Forms.TableLayoutStyleCollection> enforces the type passed to its collection operations. The [affected APIs](#affected-apis) now throw an <xref:System.ArgumentException> instead of an <xref:System.InvalidCastException> if the input is not of type <xref:System.Windows.Forms.TableLayoutStyle>.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+Previously, if the input couldn't be converted to type <xref:System.Windows.Forms.TableLayoutStyle>, an <xref:System.InvalidCastException> was thrown.
+
+## New behavior
+
+Starting in .NET 8, if the input can't be converted to type <xref:System.Windows.Forms.TableLayoutStyle>, an <xref:System.ArgumentException> is thrown.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change helps to make exception types consistent across the code base.
+
+## Recommended action
+
+For most scenarios, this change should not have a significant impact. However, if you previously handled <xref:System.InvalidCastException>, update your code to handle <xref:System.ArgumentException> instead.
+
+## Affected APIs
+
+- <xref:System.Windows.Forms.TableLayoutStyleCollection.System%23Collections%23IList%23Add(System.Object)?displayProperty=fullName>
+- <xref:System.Windows.Forms.TableLayoutStyleCollection.System%23Collections%23IList%23Insert(System.Int32,System.Object)?displayProperty=fullName>
+- <xref:System.Windows.Forms.TableLayoutStyleCollection.System%23Collections%23IList%23Remove(System.Object)?displayProperty=fullName>
@@ -0,0 +1,42 @@
+---
+title: "Breaking change: Forms scale according to AutoScaleMode"
+description: Learn about the breaking change in .NET 8 for Windows Forms where top-level windows in PerMonitorV2-mode apps scale according to AutoScaleMode.
+ms.date: 01/31/2023
+---
+# Forms scale according to AutoScaleMode
+
+In <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2>-mode apps, Windows Forms has been using linear sizes (also known as DPI-scaled sizes) provided by Windows for top-level windows, regardless of the <xref:System.Windows.Forms.AutoScaleMode>. This implementation was problematic when using the <xref:System.Windows.Forms.AutoScaleMode.Font?displayProperty=nameWithType> scaling mode, where <xref:System.Windows.Forms.Form> scaling should be non-linear. The child controls are scaled non-linearly and depend on the font that was assigned to the <xref:System.Windows.Forms.Form> or child controls.
+
+This change enables `WM_GETDPISCALEDSIZE` message handling for top-level <xref:System.Windows.Forms.Form> objects. It utilizes [WM_GETDPISCALEDSIZE](/windows/win32/hidpi/wm-getdpiscaledsize) to let Windows know that the <xref:System.Windows.Forms.Form> may need non-linear sizes depending on <xref:System.Windows.Forms.AutoScaleMode>.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+Previously, in <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2>-mode apps, top-level windows were scaled by Windows and disregarded <xref:System.Windows.Forms.AutoScaleMode> as specified in the WinForms application. This implementation led to inconsistent scaling between <xref:System.Windows.Forms.Form> objects and their child controls.
+
+## New behavior
+
+In <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2>-mode apps, top-level windows (such as [Forms](xref:System.Windows.Forms.Form)) are scaled according to <xref:System.Windows.Forms.AutoScaleMode>. This implementation ensures that top-level windows scale consistently with their child controls.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change was made to improve the high-DPI experience for Windows Forms apps in <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2> mode.
+
+## Recommended action
+
+No action is required.
+
+## Affected APIs
+
+N/A
+
+## See also
+
+- [Top-level forms scale minimum and maximum size to DPI](forms-scale-size-to-dpi.md)