Documenting .NET Core MSBuild targets and properties/CSPROJ

[guardrex]

This has been coming up more and more as we go. There have been numerous requests for help on Slack chat, several on SO, and a question on the Standup: https://youtu.be/c9Ub4uwjlbo?list=PL0M0zPgJ3HSftTAAHttA3JQU4vOjXFquF&t=3677.

@mairaw mentioned to me on Slack that props and targets perhaps are best explained as part of a topic that addresses .NET Core-specific csproj generally ... not so much just "targets and properties" disconnected from the project file.

Current info can be found in the tutorials and topics such as A mapping between project.json and csproj properties, Additions to the csproj format for .NET Core, and Packages, Metapackages and Frameworks. What's been happening quite a bit I think is that devs end up digging around in ...

https://github.com/dotnet/sdk/tree/master/src/Tasks/Microsoft.NET.Build.Tasks/targets

... to find useful/helpful props and targets. I think we all agree that that's not a good UE.

This issue addresses the need to have a clearly-visible topic for the project file that isn't migration-based, perhaps with a companion reference topic on only targets and properties in a tables format. Those could pertain to sdk, websdk, or both; but I suggest getting the websdk bits covered somewhere clearly visible in addition to merely covering the sdk ones.

cc/ @dasMulli ... Who has helped hundreds of devs with props/targets for .NET Core. I hope he'll make some observations for this issue.

[BillWagner]

Related to this topic we should provide guidance for how to configure client side builds (npm, grunt, gulp tasks) for CI builds.

[dasMulli]

There are likely at least two distinct concerns here:

1. Things to use for configuring properties and items that the SDK / build targets will understand.
   e.g. things like CopyLocalLockFileAssemblies, RuntimeFrameworkVersion.
2. Things available in custom targets and when they will be available (=> knowing what to put in AfterTargets / DependsOnTargets).
   e.g. OutputPath, DocumentationFile etc.
   This might also include common items and which target generates them.. for example, knowing that depending on ResolvePackageDependenciesForBuild enables accessing @(PackageDefinitions) and @(PackageDependencies) items, which allowed me to create a reverse dependency list.

[nguerrera]

As part of this, the documentation for BaseIntermediateOutputPath needs to indicate that it must not be set in the body of a <Project Sdk="Microsoft.NET.Sdk">. See dotnet/sdk#1518 (comment)

[guardrex]

Cross ref (might be good to include something on <RunWorkingDirectory>): https://github.com/aspnet/websdk/issues/238

[dougbu]

Please include information about breaking changes affecting project files after migration from the "old style". Hit the breaking change described at https://github.com/dotnet/project-system/blob/master/docs/configurations.md over the weekend and didn't find that page 'til @natemcmaster told me about it. Need something better than tribal knowledge here…

[Zastai]

Please also document all properties that have special meaning for the compiler etc.
I was bitten by setting an Instrument property, which apparently triggers the use of an undocumented C# compiler option (at least it's not listed here).
I'm not sure it makes sense to impact the user namespace like that; such flags could/should be named something like CscInstrument/C#.Instrument/Csc:Instrument.

[mairaw]

From @proog:
"The csproj reference topic lists the two main SDKs that can be specified in the Sdk attribute of a element.

While it does have a vague mention of the SDK being a "set of tasks and targets," it does not explain which, and perhaps more importantly does not explain what the consequences of choosing one over the other is.

In my opinion it would be helpful to have a paragraph dedicated to choosing the right SDK, or a reference to a more in-depth explanation of their differences."

[dasMulli]

ad SDKs: I guess this is about web vs non-web Sdk= project elements.

People editing the csproj by hand seem to get bitten by the different globs in these two since they have different globs for things like json files..

is there a structure proposal yet? single page or a "customize your build" node?

Topics that have come up across repos and stack overflow a lot and would potentially be useful in docs:

• How do I set X for more projects? > Link to https://docs.microsoft.com/en-us/visualstudio/msbuild/customize-your-build#use-case-multi-level-merging for Directory.Build.props
  • maybe example for setting <VersionPrefix>, <Author>, <LangVersion> etc. for a solution.
• PDB-related settings and how it affects VS.
• How do I include or exclude files in/from the publish output?
  • Show <None Update="**/my_pattern/**" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" /> - https://stackoverflow.com/questions/44374074/copy-files-to-output-directory-using-csproj-dotnetcore/44378406#44378406
  • Note that CopyToPublishDirectory is an addition to the SDK-based projects.
  • Note that PreserveNewest should be preferred over Always since latter to be able to build incrementally (-> build time).
  • Explain that web projects may Content instead of None for certain paths and patterns.
    • currently this is everything in wwwroot\**, .json and .config files.
  • Show how to use LinkBase to include content from outside the project folder in a different subdirectory.
    • e.g. <Content Include="../shared-configs/**" LinkBase="config/" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
• How to set runtime options in the csproj file (-> runtimeconfig.json)
  • e.g. server GC mode, globalization invariant mode
• How to specify the build target directory/directories
  • AppendTargetFrameworkToOutputPath is useful for single-TFM projects for ppl converting from netfx to netstandard but don't want additional subdirectories in bin/[Configuration] to not break existing tooling.
  • Redirect output via OutputPath - there have been discussions about OutDir vs OutputPath
    • BaseOutputPath to move bin\ somewhere else entirely
  • Show workarounds for redirecting obj\ to somewhere else. This needs some more hacks since BaseIntermediateOutputPath needs to be set before(!) the imported SDK props so ideally in an Directory.Build.props file or using the explicit SDK import syntax instead of the project-level Sdk attrbute.
  • Maybe have an example of how to have two csproj file in the same directory for sharing source - e.g. https://github.com/SabotageAndi/NewCSProj/tree/master/MultipleProjecsInSameFolder
• Show how to use before and after build targets to execute msbuild tasks or scripts via <Exec>.
  • Highlight that build events (PreBuildEvent / PostBuildEvent) are deprecated and should no longer be used, esp. not in sdk-style csproj files since nearly all important properties will be captured in an unfinished/wrong state.
    • VS 15.3+ using new project system now emits targets using <Exec> when using the project property dialogs for pre-/postbuild events.
  • Show an alternative for $(SolutionDir) using Directory.Build.props in the .sln directory since this is only set when building a solution file or through visual studio, but not during Restore (=> setting BaseIntermediateOutputPath based on $(SolutionDir) just doesn't work in most scenarios)
  • Show examples for pre / post build targets for multi-targeting builds with differences:
    • Run once - "outer build"
    • Run for each TFM - "inner build"
• Set startup command line arguments for launching in VS or dotnet run
  • RunWorkingDirectory / RunArguments / StartupArguments
• "How do I get all the NuGet dll files into the output directory for my 10 year old reflection logic?"
  • CopyLocalLockFileAssemblies
  • Show how to use DependencyContext APIs instead
• How do I reference individual DLL files?

maybe cc @SabotageAndi for additional suggestions

[dasMulli]

From feedbacks via other channels: Incremental builds are only sparsely documented. I strongly agree since I recently needed to look at msbuild source code for an edge case that wasn't documented (this SO question).
But I guess this is more VS docs than .NET docs or does anyone want to see a "good example" of an incrementally buildable target? (I can't think of a good example use case off the top of my head)

[dasMulli]

Missed DefaultItemExcludes (and DefaultItemExcludesInProjectFolder) which would be a good fit for https://github.com/dotnet/docs/blob/master/docs/core/tools/csproj.md which already has EnableDefaultItems and EnableDefaultCompileItems. Thanks to @DanielTheCoder for reminding me!
There are some more details on the various switches for default globs. There is also a VS issue for compile items once the glob is turned off: dotnet/sdk#1562 / dotnet/sdk#1157

[gewarren]

Add info about the degree to which the .NET Core SDK supports existing project files (not SDK style).

[dasMulli]

Add info about the degree to which the .NET Core SDK supports existing project files (not SDK style).

I believe the communication from the SDK/CLI team over the years was along the lines of "not officially supported, it may work for you and only you".
Would be good to have that somewhere as some GH issues have been raised in the past, especially during 1.0-2.0 time (not sure if there were many recently).

[gewarren]

I've created manageable chunk issues to track the remaining work on https://docs.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props. Closing this one out.