MSBuild: Generate XML documentation for main project but not dependency projects

6
votes

I have a .sln file with several projects in it. To keep this simple, let's call them...

  • ProjectA
  • ProjectB
  • ProjectC

...where A is the main project which references B and C. My goal is to update my build script to generate an XML "Intellisense" documentation file for ProjectA, without giving build warnings about missing documentation from B and C.

Current Build Script

I have an MSBuild script which includes the following in the build step:

<PropertyGroup>
    <CustomOutputPath>C:\build\output\</CustomOutputPath>
</PropertyGroup>
<ItemGroup>
    <Projects Include="ProjectA\ProjectA.csproj">
        <Properties>OutputPath=$(CustomOutputPath)</Properties>
    </Projects>
</ItemGroup>
<MSBuild Projects="@(Projects)" />

(There are actually multiple Projects listed in the ItemGroup, but again, let's keep this simple.)

When I run the build script, it's smart enough to compile B, C, and A for me, even though I've only specified A. All output appears in the "CustomOutputPath" location.

The closest I've gotten...

If I add a 'DocumentationFile' property to my Project entry...

<ItemGroup>
    <Projects Include="ProjectA\ProjectA.csproj">
        <Properties>OutputPath=$(CustomOutputPath);DocumentationFile=ProjectA.xml</Properties>
    </Projects>
</ItemGroup>

...then 'ProjectA.xml' appears in "CustomOutputPath". However, I also get files named 'ProjectA.xml' in the project folder for all three projects:

  • ProjectA/ProjectA.xml
  • ProjectB/ProjectA.xml
  • ProjectC/ProjectA.xml

These files contain the "Intellisense" documentation for their respective projects, even though they're all named "ProjectA.xml".

This creates undesired and misleadingly-named files in the project folders, and (more importantly) generates build warnings for the missing documentation comments in B and C. I don't want to add documentation comments to those projects, so I'd prefer to find a way to have MSBuild generate the documentation only for ProjectA.

Can anyone provide any insight, or an alternative solution?

1
msbuildmsbuild-task
At this point, I haven't found a direct solution to this problem. I've suppressed the build warnings with Skeet's #pragma suggestion (stackoverflow.com/a/203873/38657), and have deleted the extra .xml files per Alexey's answer below. But these are all workarounds. Hopefully a cleaner solution will present itself. – Nate Sauber
Any updates? This is so nasty problem... – mynkow
Nope, no insights here. Honestly, I've moved away from MSBuild where possible. Psake, Rake, and Fake have been much easier to work with (though I haven't tackled this problem in any of them). – Nate Sauber

1 Answers

2
votes

Based on what I've found - DocumentationFile is a global-level property (and will be used in creation of DocFileItem - global level items list). From my understanding you won't be able to alter it in any easy way in a single logical script.

What you can do is to define special target in separate file that will be imported to every proj file (directly editing proj files or using properties like $CustomBeforeMicrosoftCommonTargets) that will overwrite DocumentationFile with project-dependent value. As a result - you probably can generate different documentation file names for different projects.

Another solution - just clean-up all unnecessary doc files right after all projs were built.