How to properly specify DocumentationFile

Hi all, I am using the latest preview of MsBuild 15 and I have a multitarget project file targeting both net40 and netstandard1.6. I am struggling with specifying <DocumentationFile> correctly.

For any path I would specify, the resultant xml file after the build will be both in that path and two target output directories.

For instance, if I specify

<DocumentationFile>doc.xml</DocumentationFile>

Then the xml file will be generated both in my project dir and bin\net40 and bin\netstandard1.6.

I need those xml documentation files only in my bin\net40 and bin\netstandard1.6 directories. How can I achieve that? Also, with the current behavior, it is not clear which documentation file is copied to my project dir, because those xml documents can differ for two targets.

In earlier project versions I used to specify documentation xml path separately for Debug and Release build configurations with paths like bin\Debug\doc.xml, but with the newest MsBuild 15 it is possible to do multitargeting and the number of such paths double if I specify the dir for all possible combinations of target and build configuration.

Is there any generic good way to specify documentation file path once and get it to the right output places only?

[Zastai]

(A bit of an old ticket, but I spent some time getting this right myself, so figured I’d share.)

The problem is that the C# targets set up an ItemGroup with a DocFileItem entry based on $(DocumentationFile) at top level (i.e. NOT inside a target); that is used to pass the doc file to the C# compiler. Unfortunately, the way that is set up prevents it picking up the change to $(OutputPath) from the multi-targeting.

What you can do is to not set DocumentationFile at the project level. Instead, add this target (possibly via Directory.Build.targets so it gets used by all projects in a solution). If a project does not need the doc file to be generated (e.g. a unit test project), add a GenerateXMLDocs property, setting it to false.

  <!-- Generate a documentation file unless explicitly disabled. -->
  <Target Name="SetUpDocumentationFile" BeforeTargets="CoreCompile">
    <PropertyGroup Condition=" '$(GenerateXMLDocs)' == 'false' ">
      <DocumentationFile></DocumentationFile>
    </PropertyGroup>
    <PropertyGroup Condition=" '$(GenerateXMLDocs)' != 'false' ">
      <DocumentationFile>$([MSBuild]::NormalizePath('$(OutputPath)', '$(MSBuildProjectName).xml'))</DocumentationFile>
    </PropertyGroup>
    <ItemGroup Condition=" '$(DocumentationFile)' != '' ">
      <DocFileItem Remove="*" /> <!-- might not be strictly required -->
      <DocFileItem Include="$(DocumentationFile)" />
    </ItemGroup>
  </Target>

(To be completely safe for use in DIrectory.Build.targets, you might need to declare a CoreCompile target, in case it gets pulled in to a non-c#/vb project.)

[Zastai]

Then just <GenerateDocumentationFile>true </GenerateDocumentationFile>, without setting DocumentationFile, should do what you want. My workaround dates back to before that flag was added.