High DPI monitor breaking changes

docs/core/compatibility/8.0.md

@@ -0,0 +1,22 @@
+---
+title: Breaking changes in .NET 8
+description: Navigate to the breaking changes in .NET 8.
+ms.date: 01/19/2023
+no-loc: [Blazor, Razor, Kestrel]
+---
+# Breaking changes in .NET 8
+
+If you're migrating an app to .NET 8, the breaking changes listed here might affect you. Changes are grouped by technology area, such as ASP.NET Core or Windows Forms.
+
+[!INCLUDE [binary-source-behavioral](includes/binary-source-behavioral.md)]
+
+> [!NOTE]
+>
+> This article is a work in progress. It's not a complete list of breaking changes in .NET 8. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%208%22%20or%20label:8.0.0)%20sort:created-desc).
+
+## Windows Forms
+
+| Title                                                                                                 | Type of change    | Introduced |
+| ----------------------------------------------------------------------------------------------------- | ----------------- | ---------- |
+| [Top-level forms scale minimum and maximum size to DPI](windows-forms/8.0/forms-scale-size-to-dpi.md) | Behavioral change | Preview 1  |
+| [Anchor layout changes](windows-forms/8.0/anchor-layout.md)                                           | Behavioral change | Preview 1  |

docs/core/compatibility/includes/binary-source-behavioral.md

@@ -0,0 +1,7 @@
+This article categorizes each breaking change as *binary incompatible* or *source incompatible*, or as a *behavioral change*:
+
+- **Binary incompatible** - When run against the new runtime or component, existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
+
+- **Source incompatible** - When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
+
+- **Behavioral change** - Existing code and binaries may behave differently at run time. If the new behavior is undesirable, existing code would need to be updated and recompiled.

docs/core/compatibility/toc.yml

@@ -662,6 +662,16 @@ items:
   items:
   - name: ASP.NET Core
     items:
+    - name: .NET 8
+      items:
+      - name: Overview
+        href: 8.0.md
+      - name: Windows Forms
+        items:
+        - name: Anchor layout changes
+          href: windows-forms/8.0/anchor-layout.md
+        - name: Top-level forms scale size to DPI
+          href: windows-forms/8.0/forms-scale-size-to-dpi.md
     - name: .NET 7
       items:
       - name: API controller actions try to infer parameters from DI
@@ -1298,6 +1308,12 @@ items:
         href: wcf-client/6.0/net-standard-2-support.md
   - name: Windows Forms
     items:
+    - name: .NET 8
+      items:
+      - name: Anchor layout changes
+        href: windows-forms/8.0/anchor-layout.md
+      - name: Top-level forms scale size to DPI
+        href: windows-forms/8.0/forms-scale-size-to-dpi.md
     - name: .NET 7
       items:
       - name: APIs throw ArgumentNullException

docs/core/compatibility/windows-forms/8.0/anchor-layout.md

@@ -0,0 +1,62 @@
+---
+title: "Breaking change: Anchor layout changes"
+description: Learn about the breaking change in .NET 8 for Windows Forms where anchor layout computations have been changed to support high DPI devices.
+ms.date: 01/19/2023
+---
+# Anchor layout changes
+
+Control anchor computations have been changed to support high DPI devices. For more information about the changes, see [Anchor layout changes in .NET 8](https://github.com/dotnet/winforms/blob/main/docs/design/anchor-layout-changes-in-net80.md).
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+Certain applications using <xref:System.Windows.Forms.HighDpiMode.SystemAware?displayProperty=nameWithType> or <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2?displayProperty=nameWithType> mode and anchored controls encountered layout issues on high DPI devices.
+
+## New behavior
+
+Applications using <xref:System.Windows.Forms.HighDpiMode.SystemAware?displayProperty=nameWithType> or <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2?displayProperty=nameWithType> mode and anchored controls should have improved layout when rendered on high DPI devices.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change is part of a broader effort to improve the Windows Forms user experience on high DPI monitors. It enables developers to use an anchored layout for applications on high DPI devices.
+
+## Recommended action
+
+If the new behavior is problematic for you, you can opt out by setting `System.Windows.Forms.AnchorLayoutV2` to `false` in your *runtimeconfig.json* file.
+
+*runtimeconfig.template.json* template file:
+
+```json
+{
+   "configProperties": {
+      "System.Windows.Forms.AnchorLayoutV2": false
+   }
+}
+```
+
+*[appname].runtimeconfig.json* output file:
+
+```json
+{
+   "runtimeOptions": {
+      "configProperties": {
+         "System.Windows.Forms.AnchorLayoutV2": false
+      }
+   }
+}
+```
+
+## Affected APIs
+
+N/A
+
+## See also
+
+- [Anchor layout changes in .NET 8](https://github.com/dotnet/winforms/blob/main/docs/design/anchor-layout-changes-in-net80.md)

docs/core/compatibility/windows-forms/8.0/forms-scale-size-to-dpi.md

@@ -0,0 +1,64 @@
+---
+title: "Breaking change: Top-level forms scale to DPI"
+description: Learn about the breaking change in .NET 8 for Windows Forms where top-level forms scale their minimum and maximum size values according to the DPI of the monitor.
+ms.date: 01/19/2023
+---
+# Top-level forms scale minimum and maximum size to DPI
+
+Top-level forms in Windows Forms now scale their <xref:System.Windows.Forms.Form.MinimumSize> and <xref:System.Windows.Forms.Form.MaximumSize> values according to the dots per inch (DPI) of the monitor when running in <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2?displayProperty=nameWithType> mode.
+
+## Version introduced
+
+.NET 8 Preview 1
+
+## Previous behavior
+
+In .NET 8, the <xref:System.Windows.Forms.Form.MinimumSize> and <xref:System.Windows.Forms.Form.MaximumSize> values for top-level forms remained constant regardless of the application DPI mode and the DPI of the monitor where the form is rendered. This sometimes resulted in scaling limitations of the top-level form.
+
+You can also opt into this behavior in .NET 7. To opt in, set the `System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi` runtime configuration option described in the [Recommended action](#recommended-action) section.
+
+## New behavior
+
+Starting in .NET 8, top-level forms scale their <xref:System.Windows.Forms.Form.MinimumSize> and <xref:System.Windows.Forms.Form.MaximumSize> values according to the DPI of the monitor when running in <xref:System.Windows.Forms.HighDpiMode.PerMonitorV2?displayProperty=nameWithType> mode. The behavior of your app might change in the following ways:
+
+- Run-time dependencies might be impacted when the minimum and maximum size of the form change.
+- New <xref:System.Windows.Forms.Form.MinimumSizeChanged> and <xref:System.Windows.Forms.Form.MaximumSizeChanged> events might be raised.
+- The scaled form size now has new constraint values for the minimum and maximum sizes.
+
+## Change category
+
+This change is a [*behavioral change*](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change is part of a broader effort to improve the Windows Forms user experience on high DPI monitors. It enables developers to set minimum and maximum sizes for top-Level forms without having to take the DPI of the monitor into account.
+
+## Recommended action
+
+If the new behavior is problematic for you, you can opt out by setting `System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi` to `false` in your *runtimeconfig.json* file.
+
+*runtimeconfig.template.json* template file:
+
+```json
+{
+   "configProperties": {
+      "System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi": false
+   }
+}
+```
+
+*[appname].runtimeconfig.json* output file:
+
+```json
+{
+   "runtimeOptions": {
+      "configProperties": {
+         "System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi": false
+      }
+   }
+}
+```
+
+## Affected APIs
+
+N/A