[Breaking change]: `DefineConstants` items for target frameworks are no longer available at evaluation-time

[baronfel]

Description

In .NET 10, we moved the generation of several DefineConstants MSBuild Property values related to the TargetFramework and Runtime (NET/NETFRAMEWORK/NETSTANDARD and OR_GREATER variants) used for the given build from evaluation-time to target-execution time. This was done for several reasons, including protecting critical areas of the build pipeline from inadvertent user corruption (via the use of /p:DefineConstants and friends), as well as making the overall build changes more understandable.

As a result, users who tried to key off of these DefineConstants values in Conditions at evaluation time will find those Conditions no longer triggering.

Version

.NET 10

Previous behavior

Usage of the the (NET/NETFRAMEWORK/NETSTANDARD)[VERSION][_OR_GREATER] DefineConstants (like NET, NET_452_OR_GREATER, NET9_0_OR_GREATER, and so on) worked at evaluation time, like the following in a project file:

<ItemGroup Condition="$(DefineConstants.Contains('NET_9_0_OR_GREATER'))">
  <PackageReference Include=".." Version=".." />
</ItemGroup>

New behavior

Usage of the the (NET/NETFRAMEWORK/NETSTANDARD)[VERSION][_OR_GREATER] DefineConstants (like NET, NET_452_OR_GREATER, NET9_0_OR_GREATER, and so on) will not work directly in a project file. Instead, users should use the documented TargetFramework comparison functions to perform such logic:

<ItemGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('net9.0', '$(TargetFramework)'))">
  <PackageReference Include=".." Version=".." />
</ItemGroup>

Type of breaking change

• Binary incompatible: Existing binaries might 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 might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Direct access/manipulation of DefineConstants led to users overwriting the values, and we also needed the ability to call a Target to make those values get computed in other, more complex MSbuild orchestration that other tools required.

Recommended action

DO NOT

• directly inspect DefineConstants properties for TFM-related values during evaluation

DO

• use documented MSBuild property functions to check for TargetFramework compatibility
• continue to use DefineConstants in Conditions if they are constants that you control

Feature area

SDK

Affected APIs

No response