[Feature Request]: Better documentation and examples around BuildManager

[hknielsen]

Summary

General MSBuild documentation are really good, but when it comes to BuildManager the documentation are almost non existent, the API documentation contains no examples or further explanation.

The only way to understand BuildManager are to go digging in MSBuild source code.
What im specifically looking for:

• Logging, I couldnt find any in-memory public loggers, so had to implement my own. Only options was primarily Console or file loggers, but very little info of how to do this.
• When to use BuildRequestData or GraphBuildRequestData
• Better explanation about caching, ie. why use BuildManager.DefaultBuildManager reading this seem to suggest shared cache
• When to use InputResultsCacheFiles/OutputResultsCacheFile, its not intuitive. In the beginning I thought it was cache of Target Inputs/Outputs caching, but it dosnt seem thats the case.

General best practices, and usage examples would be really beneficial in this area.

Background and Motivation

Using more time than needed looking at MSBuild source code to know what to do

Proposed Feature

Add more documentation :)

Alternative Designs

No response

[rainersigwald]

A reasonable request! Quick answers:

• Logging, I couldnt find any in-memory public loggers, so had to implement my own. Only options was primarily Console or file loggers, but very little info of how to do this.

File/console/binlog are what we offer builtin; writing your own in-memory logger makes sense to me.

• When to use BuildRequestData or GraphBuildRequestData

Use BuildRequestData unless you are explicitly trying to launch a graph build, which you probably aren't.

• Better explanation about caching, ie. why use BuildManager.DefaultBuildManager reading this seem to suggest shared cache

Generally, you can use DefaultBuildManager for a small application where you don't want to think about things, but if you're writing a full-featured build host create your own BuildManager and use it consistently.

• When to use InputResultsCacheFiles/OutputResultsCacheFile, its not intuitive. In the beginning I thought it was cache of Target Inputs/Outputs caching, but it dosnt seem thats the case.

This is an advanced feature you probably don't want to use; see https://github.com/dotnet/msbuild/blob/3b59113aa9333f52efc4ab6bf96d713d05d604d1/documentation/specs/static-graph.md#single-project-isolated-builds. It's useful for a higher-level build engine that treats "MSBuild project execution" as a single unit.

[hknielsen]

So a bit of context, I am writing a long living build host that we will ipc from Unity for invoking builds from for our work towards MSBuild.
What I want to achieve is to keep as much as possible cached in memory, and if possible on disk, for maximising iteration time using incremental builds.
For that we will by default enforce static graph and isolated builds when we execute the build/restore through the BuildManager.
Reading the inputs/output cache files, its exactly what we want. While briefly looking into them, I didnt find any tests using these files, are they used anywhere today?

[hknielsen]

@rainersigwald a bit more questions about BuildManager and ProjectCollection and documentation.

We have 1 BuildManager thats shared for all our compilations, but separate ProjectCollections for each "Project" graph.
As far as I can read from the ProjectCollection comments is that this is allowed, the only restriction is that you are not allowed to run Build concurrently on two different ProjectCollection's, is this true? Or is it more "safe" to also keep a shared ProjectCollections.
We are using the ProjectCollections to Evaluate Projects as well, to get Items, and properties for projects, do we need to also lock these calls, or are they thread safe?

We are running into exceptions happening in the ProjectCollection.LoadProject, but that seem to be because of Project Reevaluation, and the LoggerService are null, ill report a seperate bug on that

[hknielsen]

@rainersigwald additional questions that would be nice to get added to the documentation.

ProjectPluginCache:

• Its owned and created by the BuildManager, there can be multiple and there's no order guarantee AFAICT.
• DesignTime are bypassing the ProjectPluginCache, for reasons?
  • Is it because its expected it would be bad to use the DesignTime build to populate the cache?

Evaluation:

• Are that only happening on the root node? Ie. if using InProc, all evaluation would happen with the build manager.
  • I was looking into how the ExecutionContext is working with Nodes and how Shared state are shared across nodes, fx. when not using SharingPolicy.Isolated