net5.0 TFM defines both NET5_0 and NETCOREAPP3_1

[Tratcher]

Description

When building a project that cross compiles between net5.0 and netcoreapp3.1 there's an ordering problem with the #if's. If the NETCOREAPP3_1 condition is put first then the net5.0 TFM will compile using it, but if the NET5_0 condition is first then that is choosen.

Configuration

5.0.100-preview.8.20417.9 SDK

Windows 10 2004 (19041.450) x64

Regression?

Yes. This was working in prior preview SDKs when using NETCOREAPP5_0.

Other information

Program.cs:

using System;
using System.Runtime.CompilerServices;

namespace TfmConsole
{
    class Program
    {
        static void Main(string[] args)
        {
            Broken();
            Fixed();
        }

        static void Broken()
        {
            Console.WriteLine("Hello Broken World! " + Environment.Version);
#if NETCOREAPP3_1
            Console.WriteLine("NETCOREAPP3_1");
#elif NET5_0
            Console.WriteLine("NET5_0");
#elif NETCOREAPP5_0
            Console.WriteLine("NETCOREAPP5_0");
#else
#error A target framework was added to the project and needs to be added to this condition.
#endif
        }
        static void Fixed()
        {
            Console.WriteLine("Hello Fixed World! " + Environment.Version);
#if NET5_0
            Console.WriteLine("NET5_0");
#elif NETCOREAPP5_0
            Console.WriteLine("NETCOREAPP5_0");
#elif NETCOREAPP3_1
            Console.WriteLine("NETCOREAPP3_1");
#else
#error A target framework was added to the project and needs to be added to this condition.
#endif
        }
    }
}

csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net5.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>

</Project>

Output:

C:\temp\TfmConsole\TfmConsole>dotnet run --framework netcoreapp3.1
Hello Broken World! 3.1.7
NETCOREAPP3_1
Hello Fixed World! 3.1.7
NETCOREAPP3_1

C:\temp\TfmConsole\TfmConsole>dotnet run --framework net5.0
Hello Broken World! 5.0.0
NETCOREAPP3_1
Hello Fixed World! 5.0.0
NET5_0

C:\temp\TfmConsole\TfmConsole>dotnet run --framework netcoreapp5.0
Hello Broken World! 5.0.0
NETCOREAPP3_1
Hello Fixed World! 5.0.0
NET5_0

[Dotnet-GitSync-Bot]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[Tratcher]

Simpler repro:

            Console.WriteLine("Hello Broken World! " + Environment.Version);
#if NETCOREAPP3_1
            Console.WriteLine("NETCOREAPP3_1");
#endif
#if NET5_0
            Console.WriteLine("NET5_0");
#endif

Output:

C:\temp\TfmConsole\TfmConsole>dotnet run --framework netcoreapp3.1
Hello Broken World! 3.1.7
NETCOREAPP3_1

C:\temp\TfmConsole\TfmConsole>dotnet run --framework net5.0
Hello Broken World! 5.0.0
NETCOREAPP3_1
NET5_0

It looks like both NETCOREAPP3_1 and NET5_0 are being defined by the net5.0 TFM.

[Tratcher]

This also reproduces with the 5.0.100-rc.1.20452.6 SDK.

[sebastienros]

Note that there is no need to multi target to repro the issue. Any app with <TargetFramework>net5.0</TargetFramework> will have NETCOREAPP3_1 defined.

[benaadams]

Is is so apps with NETCOREAPP3_1 defined that haven't been updated for .NET 5 don't revert to a pre-core 3.1 behaviour? (e.g. is NETCOREAPP2_0 also defined?

[sebastienros]

NETCOREAPP is defined, not NETCOREAPP2_0

[Pilchie]

Tag @marcpopMSFT

[dougbu]

Wow, it looks like this behaviour (which violates the Principle of Least Surprise) is intentional ☹️ See

sdk/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.Sdk.BeforeCommon.targets

Lines 214 to 221 in 9b383d6

	<!-- Add conditional compilation symbols for target platform backwards compatibility. -->
	<Target Name="GeneratePlatformCompatibleDefineConstants"
	Condition=" '$(DisableImplicitFrameworkDefines)' != 'true' and '$(TargetPlatformIdentifier)' != '' and '$(TargetFrameworkIdentifier)' == '.NETCoreApp' and $([MSBuild]::VersionGreaterThanOrEquals($(TargetFrameworkVersion), 5.0)) " >
	<ItemGroup>
	<_SupportedPlatformCompatibleVersions Include="@(SdkSupportedTargetPlatform)" Condition=" %(Identity) != '' and $([MSBuild]::VersionLessThan(%(Identity), $(TargetPlatformVersion))) " />
	<_ImplicitDefineConstant Include="@(_SupportedPlatformCompatibleVersions->'$(TargetPlatformIdentifier.ToUpper())%(Identity)'->Replace('.', '_'))" />
	</ItemGroup>
	</Target>

Why❔ And why isn't there an msbuild property that can disable the extra defines (and only the extra defines)❔

[Tratcher]

PR: #11236
Spec: https://github.com/dotnet/designs/blob/master/accepted/2020/net5/net5.md#preprocessor-symbols

"In order to make it easier to update code, especially when doing multi-targeting, we should make them additive, so that when targeting net6.0 both NET6_0 and NET5_0 are defined." Surprise!

[sharwell]

It's fine if the SDK defines both NETCOREAPP and NET5_0 (the former is allowed to be renamed to just NET but not required). However, the SDK must not define both NETCOREAPP3_1 and NET5_0. Doing so would break the entire mental model of the feature and we'll be stuck with the ugly workaround of writing custom build tooling that fails the build if a user fails to manually remove the extraneous definition.

[dougbu]

ae54a52 introduced this behaviour.

[dougbu]

As @jaredpar asked, how should we detect the TFM is exactly netcoreapp3.1 in C#❔

The options aren't pretty:

<ItemGroup>
   <SdkSupportedTargetPlatform Remove=".NETCoreApp,Version=v3.1" Condition=" '$(TargetFramework)' !- 'netcoreapp3.1' " />
</ItemGroup>

or use

#if !NET5_0 && NETCOREAPP3_1

everywhere you'd previously use

#if NETCOREAPP3_1

and be very careful when attempting to detect new TFMs e.g. the following won't error out from here on

#if NETCOREAPP5_0
internal static readonly Version Http2Version = HttpVersion.Version20;
internal static readonly Version Http11Version = HttpVersion.Version11;
#elif NETCOREAPP3_1
internal static readonly Version Http2Version = new Version(2, 0);
internal static readonly Version Http11Version = new Version(1, 1);
#else
#error A target framework was added to the project and needs to be added to this condition.
#endif

[dsplaisted]

To clarify why we thought this was a good idea:

We think that having compilation constants that mean “version X or greater” will lead to more maintainable code than having constants that are exact matches.

If you write conditional code today for .NET 5:

#if NET5
    // Call .NET 5 API
#else
    // Fall back to .NET Core 3.1 API
#endif

Then you should expect that the .NET 5 code would continue to work for .NET 6. You shouldn’t need to write an #if today that targets exactly .NET 5 but no later versions. When .NET 6 comes out, you should be able to retarget your project to it (or add it as a new target) without having to audit all of your conditional compilation code. With the old way of defining these constants, if you compiled the code for .NET 6 then you would have gotten the .NET Core 3.1 behavior unless you updated the #if statements.

We recognize that a lot of developers won’t expect the new behavior because it is a change. However, we aren’t changing what gets defined for existing target frameworks such as .NET Core 3.1 or .NET Framework 4.8. So they will encounter the new behavior when they are adding support for .NET 5, rather than us breaking their existing code.