Docs: Misleading page : change affects all versions of .NET, not just .NET 5

[Kryptos-FR]

The page is misleading. It states that the change only affects .NET 5, but in fact it also affect any version of .NET framework if the SDK for .NET 5 has been installed (regardless of whether any other SDKs are also installed).

I have a .NET 4.5.2 solution with a few WPF and Winforms projects including one that was explicitly set to <OutputType>Exe</OutputType> to make sure the console was displayed. Upon updating Visual Studio (without any code or config change), it started to break (no console shown).

I would have expected the rule rewriting the OutputType to be guarded and check that .NET 5 is part of the targeted frameworks. Or this page to be found in a more reachable section of the documentation: it took me a while to find it because I wasn't expected a change in .NET 5 to affect .NET Framework.

Steps to reproduce

Create a new winforms app. Change the target framework to net452. Set the output type to Exe explicitly --> no console.

Related issue: https://github.com/dotnet/sdk/issues/13331

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: d8aa9669-0b6a-0429-23da-ebd62c5e6b34
• Version Independent ID: 5471792d-993c-61ce-b472-1e11b00b7adc
• Content: Breaking change: OutputType set to WinExe for WPF and WinForms apps - .NET
• Content Source: docs/core/compatibility/windows-forms/5.0/automatically-infer-winexe-output-type.md
• Product: dotnet-fundamentals
• GitHub Login: @gewarren
• Microsoft Alias: gewarren

[dsplaisted]

Thanks for reporting this, the breaking change documentation is not correct. It should say that it applies to the .NET SDK 5.0.100 and higher.

However, it is possible that we should have restricted the inference of the WinExe output type to projects targeting .NET 5 and higher (ie matching what the breaking change notification currently says). We will consider doing so, however it likely wouldn't make it until the February update of the SDK, so most people who would hit this may already have done so by then.

[StevenBonePgh]

@dsplaisted Or as I mentioned in a linked issue, you could restrict the 'infer' behavior to function only if the output type was not explicitly set. Which is what the word 'infer' implies. If I tell you explicitly what output type I want and you silently ignore my request and do something else - that is NOT inference.

If you would only infer when not otherwise explicitly set you would have achieved all of your goals without having a breaking change. At the minimum, with this sort of breaking change, I would expect a compiler warning if the output type is set without disabling inference - it would have broken me but only until I looked at the compiler warning output.

And yes, you should fix it. This is going to start hitting people as they attempt to migrate legacy projects to the SDK project format to port to .NET 5, and that will be a continual process where people can run into this for years. I lost a few days on this, no luck when searching for a possible cause, etc. My guess is others landing here have similar stories of lost time.

[vuplea]

I think there are many places where the breaking change potential of newer Sdks is not acknowledged.

I am guessing that projects should use global.json to not risk breaking changes (VS updates or Sdk installs can affect development builds, and there are CIs that do might come with an unexpected Sdk update, e.g. Microsoft-hosted agents that come with the latest VS installed - arguably a dangerous choice to such a system that does not "freeze" images though).

So I think global.json usage should be recommended, instead of considering it an advanced feature.
If this is correct, I can open a separate doc issue.

[gewarren]

@PriyaPurkayastha do you have any thoughts about using global.json to not risk breaking changes in the SDK? Also, I'm wondering if we need a separate section in the breaking change docs for SDK updates.

[dsplaisted]

We do not generally recommend pre-emptively using global.json to pin the SDK version to avoid breaking changes. We do try to avoid breaking changes, and global.json is more there as an escape hatch in case you run into one. Even then, you don't necessarily need to use global.json - you may be able to simply set up your CI to use the version of the .NET SDK that doesn't have the break, until it is fixed or you've worked around it.

@StevenBonePgh The OutputType for a project that doesn't specify it is already Library, so we couldn't change that. It looks like we will probably change the logic so it only converts Exe to WinExe when targeting .NET 5 and higher. So folks could still run into this when writing or porting projects to .NET 5, but it won't change the behavior for projects that were building with previous SDKs.