Skip to content

Commit 20e8f90

Browse files
ViktorHoferViktorHofer
authored
Don't use Targets* helper properties in libs (#64500)
* Don't use Targets* helper properties in libs projs This change makes it possible to migrate 200+ (ref+src) projects to use TargetFramework instead of TargetFrameworks which avoids the additional outer build evaluation and invocation which ultimately makes the overall build faster. Targets* properties (i.e. TargetsWindows, TargetsAnyOS, TargetsUnix, etc.) rely on the TargetFramework property which usually are set inside a project. The TargetFramework property is only available before a project specifies it if it's explicitly set in a props file or if the project is cross-targeting and the outer-build dispatches into the inner-build. During the dispatch, the TargetFramework property is passed in as a global property. Until now that behavior wasn't a problem because every libraries project cross-targeted (by setting the TargetFrameworks property) even though many only include a single TargetFramework (i.e. NetCoreAppCurrent). To allow projects to use the TargetFramework property instead of TargetFrameworks, the Targets* helper properties can't be calculated anymore early in a props file as the TargetFramework property isn't set at that time. In general, the guidance by the SDK/msbuild team is to not read from the TargetFramework property before the project sets it (in a property group). That effectively means that the TargetFramework property shouldn't be used in props files at all. Therefore these helper properties can't be used anymore for property conditions and I'm replacing their usage with TargetPlatformIdentifier comparisons for both properties and items. In nearly all cases, the Targets* helper properties can be replaced with TargetPlatformIdentifier checks on items and in the few cases where TargetsUnix or TargetsLinux marks multiple tfms as compatible, the exact tfms must be used instead for the TargetPlatformIdentifier comparison. Whenever a project needs to condition properties on the platform, I'm first setting the TargetPlatformIdentifier the same way the SDK sets it so that the SDK later doesn't need to set it again to avoid the additional expensive msbuild function call. * Use TargetFramework singular to avoid outer builds Use TargetFramework instead of TargetFrameworks property whenever a projects only targets a single target framework. This avoid unnecessary outer builds and evaluations and makes the build faster.
1 parent 55884ce commit 20e8f90

File tree

349 files changed

+931
-924
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

349 files changed

+931
-924
lines changed

‎Directory.Build.props

+1
Original file line numberDiff line numberDiff line change
@@ -305,5 +305,6 @@
305305
<PropertyGroup>
306306
<CustomBeforeNoTargets>$(RepositoryEngineeringDir)NoTargetsSdk.BeforeTargets.targets</CustomBeforeNoTargets>
307307
<CustomAfterTraversalProps>$(RepositoryEngineeringDir)TraversalSdk.AfterProps.props</CustomAfterTraversalProps>
308+
<CustomAfterTraversalTargets>$(RepositoryEngineeringDir)TraversalSdk.AfterTargets.targets</CustomAfterTraversalTargets>
308309
</PropertyGroup>
309310
</Project>

‎docs/coding-guidelines/project-guidelines.md

+49-27
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Below is a list of all the various options we pivot the project builds on:
2222
## Individual build properties
2323
The following are the properties associated with each build pivot
2424

25-
- `$(BuildTargetFramework) -> Any .NETCoreApp or .NETFramework TFM, e.g. net5.0`
25+
- `$(BuildTargetFramework) -> Any .NETCoreApp or .NETFramework TFM, e.g. net7.0`
2626
- `$(TargetOS) -> Windows | Linux | OSX | FreeBSD | [defaults to running OS when empty]`
2727
- `$(Configuration) -> Release | [defaults to Debug when empty]`
2828
- `$(TargetArchitecture) - x86 | x64 | arm | arm64 | [defaults to x64 when empty]`
@@ -37,22 +37,18 @@ Each project will define a set of supported TargetFrameworks
3737
<PropertyGroup>
3838
```
3939

40-
- `$(BuildSettings) -> $(BuildTargetFramework)[-$(TargetOS)][-$(Configuration)][-$(TargetArchitecture)]`
41-
- Note this property should be file path safe and thus can be used in file names or directories that need to a unique path for a project configuration.
42-
- The only required Build Settings value is the `$(BuildTargetFramework)` the others are optional.
43-
4440
Example:
45-
Pure netstandard configuration:
41+
Non cross-targeting project that targets .NETStandard:
4642
```
4743
<PropertyGroup>
48-
<TargetFrameworks>netstandard2.0</TargetFrameworks>
44+
<TargetFramework>netstandard2.0</TargetFramework>
4945
<PropertyGroup>
5046
```
5147

52-
All supported targets with unique windows/unix build for netcoreapp:
48+
A cross-targeting project which targets specific platform with `$(NetCoreAppCurrent)` and one .NETFramework tfm:
5349
```
5450
<PropertyGroup>
55-
<TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-Unix;$(NetFrameworkCurrent)</TargetFrameworks>
51+
<TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-Unix;$(NetFrameworkMinimum)</TargetFrameworks>
5652
<PropertyGroup>
5753
```
5854

@@ -61,15 +57,15 @@ All supported targets with unique windows/unix build for netcoreapp:
6157
A full or individual project build is centered around BuildTargetFramework, TargetOS, Configuration and TargetArchitecture.
6258

6359
1. `$(BuildTargetFramework), $(TargetOS), $(Configuration), $(TargetArchitecture)` can individually be passed in to change the default values.
64-
2. If nothing is passed to the build then we will default value of these properties from the environment. Example: `net5.0-[TargetOS Running On]-Debug-x64`.
65-
3. While Building an individual project from the VS, we build the project for all latest netcoreapp target frameworks.
60+
2. If nothing is passed to the build then we will default value of these properties from the environment. Example: `net7.0-[TargetOS Running On]-Debug-x64`.
61+
3. When building an individual project (either from the CLI or an IDE), all target frameworks are built.
6662

6763
We also have `RuntimeOS` which can be passed to customize the specific OS and version needed for native package builds as well as package restoration. If not passed it will default based on the OS you are running on.
6864

69-
Any of the mentioned properties can be set via `/p:<Property>=<Value>` at the command line. When building using our run tool or any of the wrapper scripts around it (i.e. build.cmd) a number of these properties have aliases which make them easier to pass (run build.cmd/sh -? for the aliases).
65+
Any of the mentioned properties can be set via `/p:<Property>=<Value>` at the command line. When building using any of the wrapper scripts around it (i.e. build.cmd) a number of these properties have aliases which make them easier to pass (run build.cmd/sh -? for the aliases).
7066

7167
## Selecting the correct BuildSettings
72-
When building an individual project the `BuildTargetFramework` and `TargetOS` will be used to select the closest matching TargetFramework listed in the projects `TargetFrameworks` property. The rules used to select the targetFramework will consider compatible target frameworks and OS fallbacks.
68+
When building an individual project the `BuildTargetFramework` and `TargetOS` will be used to select the compatible dependencies which are expressed as ProjectReference items.
7369

7470
## Supported full build settings
7571
- .NET Core latest on current OS (default) -> `$(NetCoreAppCurrent)-[RunningOS]`
@@ -80,37 +76,64 @@ When building an individual project the `BuildTargetFramework` and `TargetOS` wi
8076
## TargetFramework conditions
8177
`TargetFramework` conditions should be avoided in the first PropertyGroup as that causes DesignTimeBuild issues: https://github.com/dotnet/project-system/issues/6143
8278

83-
1. Use an equality check if the TargetFramework isn't overloaded with the OS portion.
79+
1. Use TargetFrameworkIdentifier to condition on an entire framework to differentiate between .NETCoreApp, .NETStandard and .NETFramework.
80+
Example:
81+
```
82+
<PropertyGroup>
83+
<TargetFrameworks>$(NetCoreAppCurrent);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
84+
</PropertyGroup>
85+
<ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">...</ItemGroup>
86+
<ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETStandard'">...</ItemGroup>
87+
<ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">...</ItemGroup>
88+
```
89+
2. Use equality checks if you want to condition on specific runtime agnostic target frameworks (i.e. without the `-windows` suffix).
8490
Example:
8591
```
8692
<PropertyGroup>
87-
<TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
93+
<TargetFrameworks>$(NetCoreAppCurrent);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
8894
</PropertyGroup>
95+
<ItemGroup Condition="'$(TargetFramework)' == '$(NetCoreAppCurrent)'">...</ItemGroup>
8996
<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">...</ItemGroup>
97+
<ItemGroup Condition="'$(TargetFramework)' == '$(NetFrameworkMinimum)'">...</ItemGroup>
9098
```
91-
2. Use a StartsWith when you want to test for multiple .NETStandard or .NETFramework versions.
99+
3. Use the `TargetPlatformIdentifier` property to condition on a .NETCoreApp platform specific target framework. Note that .NETStandard and .NETFramework target frameworks can't be platform specific.
92100
Example:
93101
```
94102
<PropertyGroup>
95-
<TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
103+
<TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-OSX;$(NetCoreAppCurrent)</TargetFrameworks>
104+
</PropertyGroup>
105+
<ItemGroup Condition="'$(TargetPlatformIdentifier)' == 'windows'">...</ItemGroup>
106+
<ItemGroup Condition="'$(TargetPlatformIdentifier)' == 'OSX'">...</ItemGroup>
107+
```
108+
Important: In contrast to the old `Targets*` checks, `TargetPlatformIdentifier` conditions apply to a single tfm only, inheritance between target frameworks can't be expressed. See the example below for Unix:
109+
```
110+
<PropertyGroup>
111+
<TargetFrameworks>$(NetCoreAppCurrent)-Unix;$(NetCoreAppCurrent)-Linux;$(NetCoreAppCurrent)-android;$(NetCoreAppCurrent)-windows</TargetFrameworks>
96112
</PropertyGroup>
97-
<ItemGroup Condition="$(TargetFramework.StartsWith('netstandard'))>...</ItemGroup>
113+
<ItemGroup Condition="'$(TargetPlatformIdentifier)' == 'Unix' or '$(TargetPlatformIdentifier)' == 'Linux' or '$(TargetPlatformIdentifier)' == 'android'">...</ItemGroup>
114+
<!-- Negations make such conditions easier to write and read. -->
115+
<ItemGroup Condition="'$(TargetPlatformIdentifier)' != 'windows'">...</ItemGroup>
98116
```
99-
3. Use a StartsWith if the TargetFramework is overloaded with the OS portion.
117+
4. Set the `TargetPlatformIdentifier` property in the project to be able to condition on it in properties in the project file.
118+
That is necessary as the SDK sets the `TargetPlatformIdentifier` in a .targets file after the project is evaluated. Because of that, the property isn't available during the project's evaluation and must be set manually.
100119
Example:
101120
```
102121
<PropertyGroup>
103-
<TargetFrameworks>netstandard2.0-windows;netstandard2.0-Unix</TargetFrameworks>
122+
<TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-android</TargetFrameworks>
123+
</PropertyGroup>
124+
<!-- DesignTimeBuild requires all the TargetFramework Derived Properties to not be present in the first property group. -->
125+
<PropertyGroup>
126+
<TargetPlatformIdentifier>$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)'))</TargetPlatformIdentifier>
127+
<DefineConstants Condition="'$(TargetPlatformIdentifier)' == 'android'">$(DefineConstants);ANDROID_USE_BUFFER</DefineConstants>
104128
</PropertyGroup>
105-
<ItemGroup Condition="$(TargetFramework.StartsWith('netstandard2.0'))>...</ItemGroup>
106129
```
107-
4. Use negations if that makes the conditions easier.
130+
5. Use negations if that makes the conditions easier.
108131
Example:
109132
```
110133
<PropertyGroup>
111-
<TargetFrameworks>netstandard2.0;net462;net472;net5.0</TargetFrameworks>
134+
<TargetFrameworks>$(NetCoreAppCurrent);netstandard2.0;net462</TargetFrameworks>
112135
</PropertyGroup>
113-
<ItemGroup Condition="!$(TargetFramework.StartsWith('net4'))>...</ItemGroup>
136+
<ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETFramework'">...</ItemGroup>
114137
<ItemGroup Condition="'$(TargetFramework)' != 'netstandard2.0'">...</ItemGroup>
115138
```
116139

@@ -119,11 +142,10 @@ Example:
119142
Library projects should use the following directory layout.
120143

121144
```
122-
src\<Library Name>\src - Contains the source code for the library.
145+
src\<Library Name>\gen - Contains source code for the assembly's source generator.
123146
src\<Library Name>\ref - Contains any reference assembly projects for the library.
124-
src\<Library Name>\pkg - Contains package projects for the library.
147+
src\<Library Name>\src - Contains the source code for the library.
125148
src\<Library Name>\tests - Contains the test code for a library.
126-
src\<Library Name>\gen - Contains source code for the assembly's source generator.
127149
```
128150

129151
## ref

‎eng/BeforeTargetFrameworkInference.targets

+18-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
<Project>
22

3-
<Import Project="$(MSBuildThisDirectory)targetframeworksuffix.props" Condition="'$(DesignTimeBuild)' == 'true'" />
3+
<PropertyGroup>
4+
<TargetPlatformSupported>true</TargetPlatformSupported>
5+
<TargetPlatformVersionSupported>true</TargetPlatformVersionSupported>
6+
7+
<!-- Value of 0.0 produces versionless SupportedOSPlatform attribute.
8+
This is required for platforms not expected to have a version,
9+
and we currently omit the version for all platforms. -->
10+
<SupportedOSPlatformVersion>0.0</SupportedOSPlatformVersion>
11+
12+
<!-- Disable setting a default Windows platform for .NETStandard and .NET Framework libraries.
13+
This ensures that the TargetPlatformIdentifier property is empty for non .NETCoreApp tfms. -->
14+
<_EnableDefaultWindowsPlatform>false</_EnableDefaultWindowsPlatform>
15+
<_targetPlatformIdentifier Condition="$(TargetFramework.Contains('-'))">$(TargetFramework.SubString($([MSBuild]::Add($(TargetFramework.IndexOf('-')), 1))))</_targetPlatformIdentifier>
16+
</PropertyGroup>
17+
18+
<PropertyGroup Condition="'$(_targetPlatformIdentifier)' != '' and '$(_targetPlatformIdentifier)' != 'windows'">
19+
<TargetPlatformVersion>1.0</TargetPlatformVersion>
20+
</PropertyGroup>
421

522
</Project>

‎eng/TraversalSdk.AfterTargets.targets

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<Project>
2+
3+
<!-- Uses the Microsoft.DotNet.Build.Tasks.TargetFramework package to filter out target frameworks from ProjectReferences. -->
4+
<PropertyGroup Condition="'$(FilterTraversalProjectReferences)' == 'true'">
5+
<BuildDependsOn>$(BuildDependsOn);ResolveP2PReferences</BuildDependsOn>
6+
<CleanDependsOn>$(CleanDependsOn);ResolveP2PReferences</CleanDependsOn>
7+
<RebuildDependsOn>$(RebuildDependsOn);ResolveP2PReferences</RebuildDependsOn>
8+
<TestDependsOn>$(TestDependsOn);ResolveP2PReferences</TestDependsOn>
9+
<VSTestDependsOn>$(VSTestDependsOn);ResolveP2PReferences</VSTestDependsOn>
10+
<PackDependsOn>$(PackDependsOn);ResolveP2PReferences</PackDependsOn>
11+
<PublishDependsOn>$(PublishDependsOn);ResolveP2PReferences</PublishDependsOn>
12+
</PropertyGroup>
13+
14+
<ItemGroup Condition="'$(FilterTraversalProjectReferences)' == 'true'">
15+
<ProjectReference Update="@(ProjectReference)" SkipGetTargetFrameworkProperties="false" />
16+
</ItemGroup>
17+
18+
</Project>

‎eng/Version.Details.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,9 @@
102102
<Uri>https://github.com/dotnet/arcade</Uri>
103103
<Sha>78eaf78761027d225030be2b28aaf4e8bf392929</Sha>
104104
</Dependency>
105-
<Dependency Name="Microsoft.DotNet.Build.Tasks.TargetFramework" Version="7.0.0-beta.22110.7">
105+
<Dependency Name="Microsoft.DotNet.Build.Tasks.TargetFramework" Version="7.0.0-beta.22111.10">
106106
<Uri>https://github.com/dotnet/arcade</Uri>
107-
<Sha>78eaf78761027d225030be2b28aaf4e8bf392929</Sha>
107+
<Sha>ff6cc4e9c3eef575f62a33a642ca80e79d27c9bb</Sha>
108108
</Dependency>
109109
<Dependency Name="Microsoft.DotNet.RemoteExecutor" Version="7.0.0-beta.22110.7">
110110
<Uri>https://github.com/dotnet/arcade</Uri>

‎eng/Versions.props

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@
6767
<MicrosoftDotNetBuildTasksArchivesVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksArchivesVersion>
6868
<MicrosoftDotNetBuildTasksInstallersVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksInstallersVersion>
6969
<MicrosoftDotNetBuildTasksPackagingVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksPackagingVersion>
70-
<MicrosoftDotNetBuildTasksTargetFrameworkVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksTargetFrameworkVersion>
70+
<MicrosoftDotNetBuildTasksTargetFrameworkVersion>7.0.0-beta.22111.10</MicrosoftDotNetBuildTasksTargetFrameworkVersion>
7171
<MicrosoftDotNetBuildTasksTemplatingVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksTemplatingVersion>
7272
<MicrosoftDotNetBuildTasksWorkloadsPackageVersion>7.0.0-beta.22110.7</MicrosoftDotNetBuildTasksWorkloadsPackageVersion>
7373
<MicrosoftDotNetRemoteExecutorVersion>7.0.0-beta.22110.7</MicrosoftDotNetRemoteExecutorVersion>

‎eng/packaging.targets

+3-3
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@
1010
<PackDependsOn>AddNETStandardCompatErrorFileForPackaging;IncludeAnalyzersInPackage;$(PackDependsOn)</PackDependsOn>
1111
<BeforePack>AddNETStandardCompatErrorFileForPackaging;IncludeAnalyzersInPackage;$(BeforePack)</BeforePack>
1212
<TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);AddRuntimeSpecificFilesToPackage;IncludeProjectReferencesWithPackAttributeInPackage</TargetsForTfmSpecificContentInPackage>
13-
<IncludeBuildOutput Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp' and '$(TargetPlatformIdentifier)' != ''">false</IncludeBuildOutput>
13+
<IncludeBuildOutput Condition="'$(TargetPlatformIdentifier)' != ''">false</IncludeBuildOutput>
1414
<!-- Don't include target platform specific dependencies, since we use the target platform to represent RIDs instead -->
15-
<SuppressDependenciesWhenPacking Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp' and '$(TargetPlatformIdentifier)' != ''">true</SuppressDependenciesWhenPacking>
15+
<SuppressDependenciesWhenPacking Condition="'$(TargetPlatformIdentifier)' != ''">true</SuppressDependenciesWhenPacking>
1616
<PackageDesignerMarkerFile>$(MSBuildThisFileDirectory)useSharedDesignerContext.txt</PackageDesignerMarkerFile>
1717
<!-- Generate packages for rid specific projects or for allconfigurations during build. -->
1818
<!-- A package isn't generated if in servicing or in runtimelab. Intended to be overridden at project level. -->
@@ -101,7 +101,7 @@
101101
DocumentationProjectOutputGroup;
102102
SatelliteDllsProjectOutputGroup;
103103
$(TargetsForTfmSpecificBuildOutput)"
104-
Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp' and '$(TargetPlatformIdentifier)' != ''">
104+
Condition="'$(TargetPlatformIdentifier)' != ''">
105105
<PropertyGroup>
106106
<RuntimeSymbolPath>$(TargetDir)$(TargetName).pdb</RuntimeSymbolPath>
107107
<_packageTargetRuntime>$(TargetPlatformIdentifier.ToLowerInvariant().Replace('windows', 'win'))</_packageTargetRuntime>

‎eng/targetframeworksuffix.props

-101
This file was deleted.

0 commit comments

Comments
 (0)