Document the import order of the common msbuild extension points.

[cdmihai]

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]

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.<Lang>.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]

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

[cdmihai]

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]

OK. Will do.