build and buildMultiTargeting folders for props files in nuget packages

[dafergu2]

While looking at changes in #8742, I seemed to recall the documentation of buildMultiTargeting stating different behavior. Specifically, looking at the statement here:

OrchardCore/src/OrchardCore/OrchardCore.Module.Targets/OrchardCore.Module.Targets.csproj

Lines 16 to 23 in 25ef9dd

	<!--
	Add the necessary '.props' and '.targets' files under the 'build\' folder of this package,
	so that a referencing project is built / packed and considered as an 'OrchardCore' module.
	When packaging a project that references this package, and that targets multiple TFMs, the
	scripts under the 'build\' folder are not executed, so we pack another '.props' file under
	the 'buildMultiTargeting\' folder, that will just import the one under the `build\` folder.
	-->

I put together a quick test app (attached) to see if I could track down the behavior.
nuget-props-test.zip

To run the test properly, build the PackTest1 lib first and copy the resulting nuget package to PackTest1/nuget folder. Then build the PackTest2 lib or the solution.

I added several prop files to different folders in the PackTest1 nuget lib.

<ItemGroup>
  <None Include="PackTest1.props" Pack="true" PackagePath="build\PackTest1.props" />
  <None Include="PackTest1-MT.props" Pack="true" PackagePath="buildMultiTargeting\PackTest1.props" />
  <None Include="PackTest131.props" Pack="true" PackagePath="build\netcoreapp3.1\PackTest1.props" />
  <None Include="PackTest150.props" Pack="true" PackagePath="build\net5.0\PackTest1.props" />
</ItemGroup>

Each of the props file has similar contents. The goal is to identify if the props file was properly included in the PackTest2 build. The build\net5.0 props file has the following contents:

<Project>
    <ItemGroup>
        <PackTestBuildProps Include="PackTest1-net50" />
    </ItemGroup>
</Project>

and the build props file has the following:

<Project>
    <ItemGroup>
        <PackTestBuildProps Include="PackTest1" />
    </ItemGroup>
</Project>

In the PackTest2.csproj, the PackTestBuildProps are printed out with:

  <Target Name="Pack2-Test" AfterTargets="Build">
    <Message Text="Pack2-Test: Found PackTestBuildProps: %(PackTestBuildProps.Identity) - TFM -> $(TargetFramework)" Importance="High" Condition="@(PackTestBuildProps->Count()) > 0"/>
    <Message Text="Pack2-Test: Finished prop test for TFM -> $(TargetFramework)" Importance="High" />
  </Target>

Here's a summary of the output I got based on different configurations of .props files in different folders. (You can see this in the comments of the PackTest1.csproj..you'll need to edit that file to test the different scenarios. Each test was:
1) Edit the PackTest1.csproj to copy different props files to different folders for the desired test
1) dotnet nuget local -c all
1) build the PackTest1.csproj again using dotnet build && cp bin/Debug/PackTest1.1.0.0.nupkg nuget
1) dotnet build in the PackTest2 folder

<!--
      Build output only PackTest1.props and PackTest1-MT.props are included.
      <None Include="PackTest1.props" Pack="true" PackagePath="build\PackTest1.props" />
      <None Include="PackTest1-MT.props" Pack="true" PackagePath="buildMultiTargeting\PackTest1.props" />

      Summary:
        `build` files are used for all TFM specific build iterations
        `buildMultiTargeting` files are used for TFM = ''

      $ dotnet build
      Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
      Copyright (C) Microsoft Corporation. All rights reserved.

        Determining projects to restore...
        Restored /Users/df/development/nuget-props-test/PackTest2/PackTest2.csproj (in 155 ms).
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/net5.0/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1 - TFM -> net5.0
        Pack2-Test: Finished prop test for TFM -> net5.0
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/netcoreapp3.1/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1 - TFM -> netcoreapp3.1
        Pack2-Test: Finished prop test for TFM -> netcoreapp3.1
        Pack2-Test: Found PackTestBuildProps: PackTest-MT - TFM ->
        Pack2-Test: Finished prop test for TFM ->
        Successfully created package '/Users/df/development/nuget-props-test/PackTest2/bin/Debug/PackTest2.1.0.0.nupkg'.

      Build succeeded.
          0 Warning(s)
          0 Error(s)
    -->

    <!--
      Build output when all props files are included
      <None Include="PackTest1.props" Pack="true" PackagePath="build\PackTest1.props" />
      <None Include="PackTest1-MT.props" Pack="true" PackagePath="buildMultiTargeting\PackTest1.props" />
      <None Include="PackTest131.props" Pack="true" PackagePath="build\netcoreapp3.1\PackTest1.props" />
      <None Include="PackTest150.props" Pack="true" PackagePath="build\net5.0\PackTest1.props" />

      Summary:
        `build\net5.0` files are used for TFM = 'net5.0'
        `build\netcoreapp3.1` files are used for TFM = 'netcoreapp3.1'
        `buildMultiTargeting` files are used for TFM = ''

      $ dotnet build
      Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
      Copyright (C) Microsoft Corporation. All rights reserved.

        Determining projects to restore...
        Restored /Users/df/development/nuget-props-test/PackTest2/PackTest2.csproj (in 135 ms).
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/net5.0/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1-net50 - TFM -> net5.0
        Pack2-Test: Finished prop test for TFM -> net5.0
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/netcoreapp3.1/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1-net31 - TFM -> netcoreapp3.1
        Pack2-Test: Finished prop test for TFM -> netcoreapp3.1
        Pack2-Test: Found PackTestBuildProps: PackTest-MT - TFM ->
        Pack2-Test: Finished prop test for TFM ->
        Successfully created package '/Users/df/development/nuget-props-test/PackTest2/bin/Debug/PackTest2.1.0.0.nupkg'.

      Build succeeded.
          0 Warning(s)
          0 Error(s)

    -->

    <!--
      Build output with only netcoreapp3.1 TFM specific props file included:

      <None Include="PackTest1.props" Pack="true" PackagePath="build\PackTest1.props" />
      <None Include="PackTest1-MT.props" Pack="true" PackagePath="buildMultiTargeting\PackTest1.props" />
      <None Include="PackTest131.props" Pack="true" PackagePath="build\netcoreapp3.1\PackTest1.props" />

      Summary:
        build\netcoreapp3.1 files are used for TFM = 'netcoreapp3.1' and TFM = 'net5.0'
        buildMultiTargeting files are used for TFM = ''

      $ dotnet build
      Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
      Copyright (C) Microsoft Corporation. All rights reserved.

        Determining projects to restore...
        Restored /Users/df/development/nuget-props-test/PackTest2/PackTest2.csproj (in 155 ms).
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/net5.0/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1-net31 - TFM -> net5.0
        Pack2-Test: Finished prop test for TFM -> net5.0
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/netcoreapp3.1/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1-net31 - TFM -> netcoreapp3.1
        Pack2-Test: Finished prop test for TFM -> netcoreapp3.1
        Pack2-Test: Found PackTestBuildProps: PackTest-MT - TFM ->
        Pack2-Test: Finished prop test for TFM ->
        Successfully created package '/Users/df/development/nuget-props-test/PackTest2/bin/Debug/PackTest2.1.0.0.nupkg'.

      Build succeeded.
          0 Warning(s)
          0 Error(s)

    -->

    <!--
      Build output with only net5.0 TFM specific props file included:

      <None Include="PackTest1.props" Pack="true" PackagePath="build\PackTest1.props" />
      <None Include="PackTest1-MT.props" Pack="true" PackagePath="buildMultiTargeting\PackTest1.props" />
      <None Include="PackTest150.props" Pack="true" PackagePath="build\netcoreapp3.1\PackTest1.props" />

      Summary:
        `build\net5.0` files are used for TFM = 'net5.0'
        `build` files are used for TFM = 'netcoreapp3.1'
        `buildMultiTargeting` files are used for TFM = ''

      $ dotnet build
      Microsoft (R) Build Engine version 16.8.3+39993bd9d for .NET
      Copyright (C) Microsoft Corporation. All rights reserved.

        Determining projects to restore...
        Restored /Users/df/development/nuget-props-test/PackTest2/PackTest2.csproj (in 150 ms).
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/net5.0/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1-net50 - TFM -> net5.0
        Pack2-Test: Finished prop test for TFM -> net5.0
        PackTest2 -> /Users/df/development/nuget-props-test/PackTest2/bin/Debug/netcoreapp3.1/PackTest2.dll
        Pack2-Test: Found PackTestBuildProps: PackTest1 - TFM -> netcoreapp3.1
        Pack2-Test: Finished prop test for TFM -> netcoreapp3.1
        Pack2-Test: Found PackTestBuildProps: PackTest-MT - TFM ->
        Pack2-Test: Finished prop test for TFM ->
        Successfully created package '/Users/df/development/nuget-props-test/PackTest2/bin/Debug/PackTest2.1.0.0.nupkg'.

      Build succeeded.
          0 Warning(s)
          0 Error(s)
    -->

    <!-- Conclusion:

      1) Props under the build folder are always included.
          * If there is a TFM specific folder (`build\<TFM>`) in the nuget package, files in that folder are included and not the one in the build folder
          * If there is a TFM specific folder but not one for the current TFM:
              1) If there is another TFM specific folder that is compatible with the current TFM, those files are used starting
                 with the most recent.  For example when building for net5.0 and `build\netcoreapp3.1` exists but not `build\net5.0`, since net5.0 is newer than
                 netcoreapp3.1 and comptabile most of the time, the `build\netcoreapp3.1` TFM specific files are used.
              1) If there is NOT another TFM folder compatible with the current TFM, then the files in the `build` folder are used.
                 For example when building for netcoreapp3.1 and `build\net5.0` exists but not `build\netcoreapp3.1`, since `netcoreapp3.1` is older than `net5.0`,
                 the `net5.0` files are NOT used and the files in the `build` folder are used.
      1) Files in the `buildMultiTargeting` folder are always included and are executed after both TFM specific builds.  The $(TargetFramework) is ''.
    -->

@jtkech Based on the above, wouldn't we want to keep everything just the build folder unless it was specific for a TFM? It seems like the buildMultiTargeting folder is more useful for managing targets that need to be done once per nuget package rather than including .props files that sets properties needed for the assembly to be built properly? Specifically because it seems that the buildMultiTargeting folder is not included for each TFM assembly build. Unless I'm missing something?

[jtkech]

@dafergu2

The first scenario where buildMultiTargeting was needed is when packing a module multi TFMs project (referencing OC.Module.Targets as a package), and then referencing it as a package from the app. When we pack a module, through the script OrchardCore.Module.Targets.props , we rename Package.Build.props and put it in the build folder, this file contains a script so that a referencing app can see it as a module.

<ItemGroup>
  <None Include="$(MSBuildThisFileDirectory)Package.Build.props" Pack="true">
    <PackagePath>build\$(AssemblyName).props</PackagePath>
  </None>
</ItemGroup>

The problem is that when we pack such a module, packing happens after the build of both TFMs (if not yet built), then when the pack happens, the nuget script looks at the .props files to use for packing, and in that case it was not using the .props file under the build folder of the referenced OC.Module.Targets package, so even if we detect the execution of some scripts during the build, the .props file was not evaluated during the packaging, if only in the build folder, so we added to the OC.Module.Tagets a buildMultiTargeting folder including a script that just imports the .props under the build folder.

The second scenario is with the same multi TFMs module as described above but referenced as a project by a single TFM application (if the app is multi targetable it was working), here the .targets script of the OC.Module.Targets package, under its build folder was not executed, particularly the following Target that the app call on each referenced project (not package) to see if it is a module project.

<Target Name="GetModuleProjectName" Returns="@(ModuleProjectName)">
  <ItemGroup>
    <ModuleProjectName Include="$(AssemblyName)" />
  </ItemGroup>
</Target>

To fix this second scenario, we just needed to do the same for the .targets file of the OC.Module.Targets package, as we did for the .props file, put a script under buildMultiTargeting that import the one under build. Here also, even if we see the execution of the scripts during the build, the .targets file was not executed when building the application itself. In fact here, this is the application that call the above Target, but that was not evaluated to be available from a multi TFMs package (the OC.Module.Targets package referenced by the multi TFMs module referencing it).

For this 2nd scenario, see the use case in #8734