From a28f12978e0cb3e8bcd3cd51a6b9210e0ca671c6 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Jul 2026 14:28:45 -0700 Subject: [PATCH] Document the .NET Framework 4.5 `SubsystemVersion` retargeting change for Windows Forms (#54553) * Initial plan * Document the .NET Framework 4.5 SubsystemVersion retargeting change * Address review feedback on SubsystemVersion retargeting docs * Refine SubsystemVersion retargeting doc wording * Polish SubsystemVersion retargeting include wording * Finalize SubsystemVersion retargeting documentation wording * Apply suggestions from code review Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> * Apply suggestion from @adegeo * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../migration-guide/retargeting/4.5.x.md | 3 ++ .../subsystemversion-defaults-to-600.md | 35 +++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 includes/migration-guide/retargeting/winforms/subsystemversion-defaults-to-600.md diff --git a/docs/framework/migration-guide/retargeting/4.5.x.md b/docs/framework/migration-guide/retargeting/4.5.x.md index 67c82db66ddcc..f46fb48f2729c 100644 --- a/docs/framework/migration-guide/retargeting/4.5.x.md +++ b/docs/framework/migration-guide/retargeting/4.5.x.md @@ -3,6 +3,7 @@ title: Retargeting changes for migration to .NET Framework 4.5.x description: Find information about application compatibility issues that might affect your app when migrating to .NET Framework 4.5.x. ms.date: 07/31/2023 author: "chlowell" +ai-usage: ai-assisted --- # Retargeting changes for migration to .NET Framework 4.5.x @@ -43,6 +44,8 @@ This article lists the app compatibility issues that were introduced in .NET Fra [!INCLUDE[EncoderParameter ctor is obsolete](~/includes/migration-guide/retargeting/winforms/encoderparameter-ctor-obsolete.md)] +[!INCLUDE[SubsystemVersion defaults to 6.00 for .NET Framework 4.5 Windows Forms apps](~/includes/migration-guide/retargeting/winforms/subsystemversion-defaults-to-600.md)] + ### Windows Communication Foundation (WCF) [!INCLUDE [onwritebodycontents-change](~/includes/migration-guide/retargeting/wcf/onwritebodycontents-change.md)] diff --git a/includes/migration-guide/retargeting/winforms/subsystemversion-defaults-to-600.md b/includes/migration-guide/retargeting/winforms/subsystemversion-defaults-to-600.md new file mode 100644 index 0000000000000..26c677ddfd8ab --- /dev/null +++ b/includes/migration-guide/retargeting/winforms/subsystemversion-defaults-to-600.md @@ -0,0 +1,35 @@ +--- +ms.topic: include +ai-usage: ai-assisted +--- + +### SubsystemVersion defaults to 6.00 when you retarget Windows Forms applications to .NET Framework 4.5 + +#### Details + +When you build Windows Forms apps after retargeting to .NET Framework 4.5, the default `SubsystemVersion` changes from `4.00` to `6.00`. Windows uses the subsystem version when it reports some window metrics. As a result, code that calculates window or form sizes from values, such as , might produce different layout results than the same code produced on .NET Framework 4. + +#### Suggestion + +If you must preserve the .NET Framework 4 sizing behavior, set `SubsystemVersion` to `4.00` in your project file: + +```xml + + 4.00 + +``` + +You can also use the [SubsystemVersion compiler option for C#](/dotnet/csharp/language-reference/compiler-options/advanced#subsystemversion) or the [SubsystemVersion compiler option for Visual Basic](/dotnet/visual-basic/reference/command-line-compiler/subsystemversion). + +Review your code that sizes or positions Windows Forms UI with values or other `GetSystemMetrics`-based values. + +| Name | Value | +|:--------|:------------| +| Scope | Minor | +| Version | 4.5 | +| Type | Retargeting | + +#### Affected APIs + +- +-