diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md new file mode 100644 index 0000000000000..d15b9b95611ce --- /dev/null +++ b/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 | diff --git a/docs/core/compatibility/includes/binary-source-behavioral.md b/docs/core/compatibility/includes/binary-source-behavioral.md new file mode 100644 index 0000000000000..984a5b50ff59c --- /dev/null +++ b/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. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 7f24e0a5b678c..eb251ba758fb3 100644 --- a/docs/core/compatibility/toc.yml +++ b/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 diff --git a/docs/core/compatibility/windows-forms/8.0/anchor-layout.md b/docs/core/compatibility/windows-forms/8.0/anchor-layout.md new file mode 100644 index 0000000000000..40eac7b1ff4c9 --- /dev/null +++ b/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 or mode and anchored controls encountered layout issues on high DPI devices. + +## New behavior + +Applications using or 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) diff --git a/docs/core/compatibility/windows-forms/8.0/forms-scale-size-to-dpi.md b/docs/core/compatibility/windows-forms/8.0/forms-scale-size-to-dpi.md new file mode 100644 index 0000000000000..3bb4dedcc235c --- /dev/null +++ b/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 and values according to the dots per inch (DPI) of the monitor when running in mode. + +## Version introduced + +.NET 8 Preview 1 + +## Previous behavior + +In .NET 8, the and 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 and values according to the DPI of the monitor when running in 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 and 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