[Feature Request]: Improve error messages when importing props/targets that only exist in a specific distribution of MSBuild

[baronfel]

Summary

Some toolsets for MSBuild are only viable in one of our distributions of MSBuild, and when this is the case the errors that users see are hard to diagnose. We should detect this scenario and give more actionable messages so that users are able to continue their work.

Background and Motivation

In issues like #8964 we see scenarios where end users start using one distribution of MSBuild, configure that distribution to work in a particular way, and then are confused when they use another distribution of MSBuild and their builds do not work, or otherwise behave strangely.

This typically arises from the following scenario:

Using a VS-only toolset from dotnet msbuild

A user configures a Visual Studio only toolset (like the DSL Modeling tools, or Docker Compose tooling), which ships via props/targets somewhere inside the VS Install directory. The user then invokes dotnet build or dotnet msbuild, and they get a message like

error MSB4019: The imported project "<SDK_ROOT>\Microsoft\VisualStudio\v17.0<COMPONENT_DIR><TARGET_NAME>.targets" was not found. Confirm that the expression in the Import declaration "<SDK_ROOT>\Microsoft\VisualStudio\v17.0<COMPONENT_DIR><TARGET_NAME>.targets" is correct, and that the file exists on disk.

This is because of the use of $(MSBuildExtensionsPath) in the import, which in VS does point to a relevant location, but for dotnet msbuild/dotnet build points to the SDK root.

Proposed Feature

We should detect the use of the $(MSBuildExtensionsPath) property in combination with paths like "Microsoft\Visual Studio" in Imports, and issue a warning when an Import uses this pattern while executing in the dotnet msbuild/dotnet build distribution of MSBuild. Ideally, for the .NET SDK MSBuild we would be able to ask the user to use msbuild.exe from a Developer Command Prompt instead of dotnet build/dotnet msbuild.

It is possible that the inverse version of this scenario (msbuild.exe trying to build an SDK project?) might have similar gaps, but the .NET SDK version of extending MSBuild workloads doesn't rely as strongly on modifications to the SDK install locations. It's possible that workloads would be the primary area of concern for this scenario, as they are the main way that the SDK install directory is modified that I'm aware of.

Alternative Designs

Instead of this, we could work with specific VS tooling teams to ship their tasks/targets as either NuGet-delivered MSBuild SDKs or packages with MSBuild extensions. This would not be possible for all teams, and for those that it is possible for would be subject to prioritization and resourcing.