From cdd651784dd2ab48c90765a8cc9548ade82119e0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 13 Dec 2022 16:45:43 -0800 Subject: [PATCH 1/4] initial updates --- docs/core/compatibility/8.0.md | 23 +++++++++++++++++++ .../includes/binary-source-behavioral.md | 7 ++++++ 2 files changed, 30 insertions(+) create mode 100644 docs/core/compatibility/8.0.md create mode 100644 docs/core/compatibility/includes/binary-source-behavioral.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md new file mode 100644 index 0000000000000..4a5f4597a0ec7 --- /dev/null +++ b/docs/core/compatibility/8.0.md @@ -0,0 +1,23 @@ +--- +title: Breaking changes in .NET 8 +description: Navigate to the breaking changes in .NET 8. +ms.date: 12/08/2022 +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-compat](includes/binary-source-compat.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%2Fdocs%20or%20repo:aspnet%2FAnnouncements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%207%22%20or%20label:8.0.0)%20sort:created-desc). + +## ASP.NET Core + +| Title | Type of change | Introduced | +| ---------------------------------------------------------------------- | ------------------- | ---------- | +| [First change](aspnet-core/7.0/api-controller-action-parameters-di.md) | Source incompatible | Preview 2 | +| [Second change](aspnet-core/7.0/environment-variable-precedence.md) | Binary incompatible | Preview 3 | +| [Second change](aspnet-core/7.0/environment-variable-precedence.md) | Behavioral change | Preview 3 | 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..1e4477998d62e --- /dev/null +++ b/docs/core/compatibility/includes/binary-source-behavioral.md @@ -0,0 +1,7 @@ +This article categorizes each breaking change as *binary incompatible*, *source incompatible*, or a *behavioral change*: + +- **Binary incompatible** - When run against the new runtime or component, existing binaries exhibit breaking behavior changes, such as failure to load or execute, and always require recompilation. For example, removing a method from an API is a binary-incompatible change because it causes a to be thrown at run time. + +- **Source incompatible** - When recompiled using the new SDK or component or to target the new runtime, existing source code requires source changes. That is, there are new compiler errors or warnings that must be addressed. + +- **Behavioral change** - Existing code and binaries may experience different run-time behavior. If the new behavior is undesirable, existing binaries would need to be recompiled. From 45d619ee30c65fd721918ad26d46f21b0f43a980 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 20 Dec 2022 12:36:12 -0800 Subject: [PATCH 2/4] update defs to match template --- .../core/compatibility/includes/binary-source-behavioral.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/includes/binary-source-behavioral.md b/docs/core/compatibility/includes/binary-source-behavioral.md index 1e4477998d62e..f334311490910 100644 --- a/docs/core/compatibility/includes/binary-source-behavioral.md +++ b/docs/core/compatibility/includes/binary-source-behavioral.md @@ -1,7 +1,7 @@ This article categorizes each breaking change as *binary incompatible*, *source incompatible*, or a *behavioral change*: -- **Binary incompatible** - When run against the new runtime or component, existing binaries exhibit breaking behavior changes, such as failure to load or execute, and always require recompilation. For example, removing a method from an API is a binary-incompatible change because it causes a to be thrown at run time. +- **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 requires source changes. That is, there are new compiler errors or warnings that must be addressed. +- **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 experience different run-time behavior. If the new behavior is undesirable, existing binaries would need to be recompiled. +- **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. From 8158de0c599541b5e8334ed51efcddd010652d28 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 19 Jan 2023 16:21:18 -0800 Subject: [PATCH 3/4] add two winforms breaking changes --- docs/core/compatibility/8.0.md | 17 +++-- .../includes/binary-source-behavioral.md | 2 +- .../windows-forms/8.0/anchor-layout.md | 62 ++++++++++++++++++ .../8.0/forms-scale-size-to-dpi.md | 64 +++++++++++++++++++ 4 files changed, 135 insertions(+), 10 deletions(-) create mode 100644 docs/core/compatibility/windows-forms/8.0/anchor-layout.md create mode 100644 docs/core/compatibility/windows-forms/8.0/forms-scale-size-to-dpi.md diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index 4a5f4597a0ec7..d15b9b95611ce 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -1,23 +1,22 @@ --- title: Breaking changes in .NET 8 description: Navigate to the breaking changes in .NET 8. -ms.date: 12/08/2022 +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-compat](includes/binary-source-compat.md)] +[!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%2Fdocs%20or%20repo:aspnet%2FAnnouncements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%207%22%20or%20label:8.0.0)%20sort:created-desc). +> 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). -## ASP.NET Core +## Windows Forms -| Title | Type of change | Introduced | -| ---------------------------------------------------------------------- | ------------------- | ---------- | -| [First change](aspnet-core/7.0/api-controller-action-parameters-di.md) | Source incompatible | Preview 2 | -| [Second change](aspnet-core/7.0/environment-variable-precedence.md) | Binary incompatible | Preview 3 | -| [Second change](aspnet-core/7.0/environment-variable-precedence.md) | Behavioral change | Preview 3 | +| 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 index f334311490910..984a5b50ff59c 100644 --- a/docs/core/compatibility/includes/binary-source-behavioral.md +++ b/docs/core/compatibility/includes/binary-source-behavioral.md @@ -1,4 +1,4 @@ -This article categorizes each breaking change as *binary incompatible*, *source incompatible*, or a *behavioral change*: +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. 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 From 3a6414e76ccd74667b83046ea0c73d876a82d0a0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 19 Jan 2023 16:42:46 -0800 Subject: [PATCH 4/4] add to toc --- docs/core/compatibility/toc.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 3a930f76b2f8b..71154bc621d07 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -19,6 +19,16 @@ items: - name: Breaking changes by version expanded: true 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: Overview @@ -1303,6 +1313,12 @@ items: href: visualbasic.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