I second MSBuild as one of the best build systems I’ve had to work with. It absolutely has a learning curve but once you “get” how projects are evaluated and executed then you can start writing your own targets to do whatever you want.
MSBuild is very poorly documented. MSBuild is really not that good compared to what you get in FOSS land. I favor CMake over it, and personally I very much dislike CMake. The main thing in favor of CMake is you get cross platform.
The "core" of msbuild - targers, items, properties - is well documented. The actual work in normal cases is done by the vast hinterland of pre defined targets, and it's those that are badly documented. I've wasted several days reverse engineering 'ProjectReference' and only just found its detailed documentation. Fortunately you can read the source; unfortunately when you have to.
I think making it open source has come with a cultural change that's still propagating. It means not just defining the "Microsoft way" to do things but coping with myriad use cases turning up in the issue tracker.
If you think the "core" is well documented, link me the documentation which lays out all the built in targets involved in a standard c# project. Or even just a doc which describes the differences between PreBuildEvent, BeforeBuild, BeforeCompile, etc. As far as I can tell, this only exists as occasional comments in the .targets file. Msbuild documentation is horrible, without exception. When they occasionally document something it tends to miss half the optional flags and they never link the source code so it's up to you to find and correct it.
