Drafts of build scenario and persistent-problems docs

[rainersigwald]

No description provided.

[JanKrivanek]

This is golden! Conscise and comprehensive.

Please add all links. Consider adding an example or explanation to Copy task considerations. Other than those it feels ready to go!

[Copilot]

Pull Request Overview

This PR introduces two new documentation files that outline MSBuild's key challenges and usage patterns. The documents appear to be draft documentation to help understand MSBuild's performance characteristics and the variety of scenarios it supports.

• Adds documentation on persistent build performance problems in MSBuild
• Creates comprehensive documentation of build scenarios and major MSBuild users
• Provides context for performance optimization efforts by documenting bottlenecks and use cases

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
documentation/Persistent-Problems.md	Documents key performance bottlenecks including evaluation, ResolveAssemblyReferences, and copy operations
documentation/Build-Scenarios.md	Comprehensive overview of MSBuild usage scenarios from batch builds to IDE integration and major user workflows

[Copilot]

Corrected spelling of 'sytem' to 'system'.

Suggested change

	*Every* [batch build]() (absent a higher-order build system) must evaluate every project in the scope of the build. IDEs can cache evaluation and act as a higher-order builds sytem but important IDE scenarios like “first load after a repo clone” are dominated by evaluation.
	*Every* [batch build]() (absent a higher-order build system) must evaluate every project in the scope of the build. IDEs can cache evaluation and act as a higher-order builds system but important IDE scenarios like “first load after a repo clone” are dominated by evaluation.

[Copilot]

Corrected 'produced' to 'produce' for proper grammar.

Suggested change

When build is invoked, most targets can be skipped as up to date, but `ResolveAssemblyReferences` (RAR) and some of its prerequisites like `ResolvePackageAssets` cannot, because their role is to produced data used within the build to compute the compiler command line. Since they don't have concrete file outputs and their file inputs can be difficult to express (it’s the closure of all referenced assemblies), MSBuild's standard up-to-date check mechanisms can't apply.

When build is invoked, most targets can be skipped as up to date, but `ResolveAssemblyReferences` (RAR) and some of its prerequisites like `ResolvePackageAssets` cannot, because their role is to produce data used within the build to compute the compiler command line. Since they don't have concrete file outputs and their file inputs can be difficult to express (it’s the closure of all referenced assemblies), MSBuild's standard up-to-date check mechanisms can't apply.

[Copilot]

Several markdown links have empty URLs. The links for 'batch build', 'Linux', 'macOS', and 'Windows 11 24H2+ Dev Drive' should be populated with actual URLs or converted to plain text if the links are not yet available.

[Copilot]

Several markdown links have empty URLs. The links for 'batch build', 'Linux', 'macOS', and 'Windows 11 24H2+ Dev Drive' should be populated with actual URLs or converted to plain text if the links are not yet available.

[Copilot]

Multiple markdown links have empty URLs. The links for 'design-time build', 'fast up-to-date checks', 'graph-based', 'CloudBuild', and 'BuildXL' should be populated with actual URLs or converted to plain text if the links are not yet available.

Suggested change

	Because MSBuild is so dynamic, the required information is generally extracted via a [design-time build](), which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using [fast up-to-date checks]() that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are [graph-based]() builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like [CloudBuild]() or [BuildXL](). Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.
	Because MSBuild is so dynamic, the required information is generally extracted via a design-time build, which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using fast up-to-date checks that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are graph-based builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like CloudBuild or BuildXL. Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.

[Copilot]

Multiple markdown links have empty URLs. The links for 'design-time build', 'fast up-to-date checks', 'graph-based', 'CloudBuild', and 'BuildXL' should be populated with actual URLs or converted to plain text if the links are not yet available.

Suggested change

	Because MSBuild is so dynamic, the required information is generally extracted via a [design-time build](), which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using [fast up-to-date checks]() that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are [graph-based]() builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like [CloudBuild]() or [BuildXL](). Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.
	Because MSBuild is so dynamic, the required information is generally extracted via a design-time build, which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using fast up-to-date checks that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are graph-based builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like CloudBuild or BuildXL. Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.

[Copilot]

Multiple markdown links have empty URLs. The links for 'design-time build', 'fast up-to-date checks', 'graph-based', 'CloudBuild', and 'BuildXL' should be populated with actual URLs or converted to plain text if the links are not yet available.

Suggested change

	Because MSBuild is so dynamic, the required information is generally extracted via a [design-time build](), which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using [fast up-to-date checks]() that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are [graph-based]() builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like [CloudBuild]() or [BuildXL](). Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.
	Because MSBuild is so dynamic, the required information is generally extracted via a design-time build, which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using fast up-to-date checks that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are graph-based builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like CloudBuild or BuildXL. Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.

[Copilot]

Multiple markdown links have empty URLs. The links for 'design-time build', 'fast up-to-date checks', 'graph-based', 'CloudBuild', and 'BuildXL' should be populated with actual URLs or converted to plain text if the links are not yet available.

Suggested change

	Because MSBuild is so dynamic, the required information is generally extracted via a [design-time build](), which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using [fast up-to-date checks]() that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are [graph-based]() builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like [CloudBuild]() or [BuildXL](). Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.
	Because MSBuild is so dynamic, the required information is generally extracted via a design-time build, which runs a subset of the build: ideally enough to generate the information required to run a compiler, but no more. Differences between design-time build and batch build can result in errors that are extremely confusing to the users (editor squiggles that don't show up in builds, or vice versa).
	### IDE build
	After projects are loaded into an IDE, the user may invoke a build directly or indirectly (for instance with a start-debugging command). These builds can differ from batch builds dramatically, since IDEs like Visual Studio may choose to build projects in isolation. This can be motivated by supporting non-MSBuild project types (as Visual Studio does), or by a desire to reduce IDE incremental build time by avoiding MSBuild overhead using fast up-to-date checks that decide whether to invoke a project build based on a higher-order model of the project-level inputs and outputs.
	### Project-level caching
	Repos using MSBuild's project caching plugin system are graph-based builds that consult the cache plugin before starting to build each project. The cache plugin can provide cached results for a project based on the state of the system or allow the build to continue (and possibly add results to a cache).
	Because the build is graph-based, graph-construction time (dominated by evaluation time) is a major factor for these builds when up to date or mostly cached.
	### Higher-order build systems
	MSBuild can be invoked as part of a higher-order build system like CloudBuild or BuildXL. Generally in these cases the higher-order build system often constructs and walks the graph, making MSBuild evaluation and execution time (of only out-of-date projects) the critical path.