MSBUILD Generate xml documentation file for all projects in solution (without touching the projects)

Question

I'm trying to create the XML documentation for all the projects in the solution even when the option its not checked in the project properties (and this is the key point).

I'm using TFS 2010 SP1 and tried with this "/p:TreatWarningsAsErrors=true /p:GenerateDocumentation=true" in the "MSBuild Arguments" field of my build definition. It doesn't generate anything.

I also tried with /p:DocumentationFile=foo.xml, which it does work but I assuming the file gets overridden by the last compiled project, so I tried using a variable instead but with no luck, I tried with

/p:DocumentationFile=$(Project).xml,
/p:DocumentationFile=$(localProject).xml
/p:DocumentationFile=$(localBuildProjectItem).xml

Is there a way to create the XML documentation for all the projects from within MSBUILD even though the option is not checked in the project?

PS: And yes I already see another thread similar to this but I don't want to modify the projects, that's the whole point of doing it with MSBUILD.

Thanks for your time

Answer 1

I also wanted to achieve this and finally I came up with a solution following these steps:

• Create a Directory.Build.props file in the solution root folder.
• Set GenerateDocumentationFile property to true.
• Set DocumentationFile property.

By default you would use $(OutputPath) and $(AssemblyName) properties to set the documentation file name, like this:

<DocumentationFile>$(OutputPath)$(AssemblyName).xml</DocumentationFile>

But unfortunately this does not work as Directory.Build.props file is processed first hence properties set in .csproj files are unavailable at this point.

Fortunately there is another property that gets the current project name: $(MSBuildProjectName)

The output path by default is the following:

• for Web projects: bin\
• for other projects: bin\$(Configuration)\, e.g. bin\Debug\

To decide whether a project is a web project or not I used the name of the project which ends either with .Web or .WebApi

So the complete Directory.Build.props file looks like this in my case:

<Project>
    <PropertyGroup>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
        <!-- The rest is omitted for clarity. -->
    </PropertyGroup>

    <PropertyGroup>
        <!-- warning CS1591: Missing XML comment for publicly visible type or member -->
        <NoWarn>1591</NoWarn>
    </PropertyGroup>

    <PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Web')) Or $(MSBuildProjectName.EndsWith('.WebApi'))">
        <DocumentationFile>bin\$(MSBuildProjectName).xml</DocumentationFile>
    </PropertyGroup>

    <PropertyGroup Condition="!$(MSBuildProjectName.EndsWith('.Web')) And !$(MSBuildProjectName.EndsWith('.WebApi'))">
        <DocumentationFile>bin\$(Configuration)\$(MSBuildProjectName).xml</DocumentationFile>
    </PropertyGroup>
</Project>

As you can see there is also a <NoWarn>1591</NoWarn> property set which tells the compiler not to produce warning messages for publicly visible types where XML document is missing.

Hope it helps.

Answer 2

1. Open your process template (i.e.: $/yourproject/BuildProcessTemplates/DefaultTemplate.xaml)

2. Scroll down to find the Compile the Project activity.

3. Add a new variable named DocumentationFile, type=String, scope=Compile the Project

4. Set its default value to:

   String.Format("{0}.XML", System.IO.Path.GetFileNameWithoutExtension(serverBuildProjectItem))

5. Save changes and scroll down to Run MSBuild for Project activity.

6. In CommandLineArguments, set the following value: String.Format("/p:SkipInvalidConfigurations=true {0};DocumentationFile={1}", MSBuildArguments, DocumentationFile)

7. Check-in the changes and build. This should generate the documentation even if it was not set by the project.