Document the import order of the common msbuild extension points.

cdmihai commented 6 years ago

It is not clear to users how the import order looks like, considering that there are implicit top and bottom imports for:

directory.build.props and directory.build.targets
nuget package based build logic
msbuild SDK top and bottom imports

Users need to know how to compose all three of these entities to achieve the import ordering that they want.

Nirmal4G commented 5 years ago

Current (upto v17) Import Order, with and without the SDK-style

Microsoft.Common.props

Directory.Build.props
<ProjectFileNameWithExt>.<Vendor>.<Tag>.props
MSBuildUserExtensions Wildcard-ImportBefore
MSBuildExtensions Wildcard-ImportBefore
CustomBeforeMicrosoftCommonProps
<CommonProps>
CustomAfterMicrosoftCommonProps
MSBuildUserExtensions Wildcard-ImportAfter
MSBuildExtensions Wildcard-ImportAfter

.NET SDK props

AlternateCommonProps (Added in v3) OR Microsoft.Common.props
<SDK props>

Project File

<Project File>

.NET SDK targets

<SDK Before targets> (also includes BeforeTargetFrameworkInferenceTargets; Added in v5)
<LanguageTargets> Microsoft.Common.targets
<SDK After targets>
NuGet.Build.Tasks.Pack.targets

Microsoft.\.targets

<Lang Before imports>
<Lang Compiler targets>
<Lang DesignTime targets>
Microsoft.Common.targets
<Lang After imports>

Microsoft.Common.targets

Microsoft.Common.props (if not imported before)
<ProjectFileNameWithExt>.user
MSBuildUserExtensions Wildcard-ImportBefore
MSBuildExtensions Wildcard-ImportBefore
CustomBeforeMicrosoftCommonTargets
<CommonTargets>
CustomAfterMicrosoftCommonTargets
MSBuildUserExtensions Wildcard-ImportAfter
MSBuildExtensions Wildcard-ImportAfter (NuGet Restore targets, imported here)
<ProjectFileNameWithExt>.<Vendor>.<Tag>.targets
Directory.Build.targets

Note: The Xaml, CSharp, VisualBasic, FSharp targets wrap around Common targets and have similar extension points. I didn't include the imports of the inbox targets for simplicity. You can use MSBuild Log Viewer to inspect your own projects' imports.

Nirmal4G commented 5 years ago

So, How will we put the above monstrosity into docs and make people understand them easily?

cdmihai commented 5 years ago

Thanks for looking it up. Can you create a PR and add them to https://github.com/microsoft/msbuild/tree/master/documentation? The binlog viewer should also aid users in understanding the import order.

Nirmal4G commented 5 years ago

OK. Will do.

dotnet / msbuild