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

Landholder

did you ever find a solution for this? the one below does not solve the issue – Mendelian

Nop, as far as I know, this is the best we can get – Landholder

I was thinking a possible solution, would be iterating through the sln and building the csproj separately, then DocumentationFile=.. would work, i saw this but i have never seen this type of syntax before in a build script social.msdn.microsoft.com/Forums/vstudio/en-US/… – Mendelian

Answer 1

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.

Sakti

I will mark this answer because i think its the best we can get without modifying the task, it seems that in the msbuild task the project collection really is the solutions selected in the build definition and not the individual projects of each solution – Landholder

this creates the xml file but it does not prevent the file from being replaced when building an sln with multiple projects – Mendelian

Answer 2

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.

Chalfant

Answer 3

It is possible to create an environment variable that will affect the C/C++ compiler:

from https://learn.microsoft.com/en-us/cpp/build/reference/cl-environment-variables?view=msvc-170

CL and _CL_, if defined. The CL tool prepends the options and
arguments defined in the CL environment variable to the command-line
arguments, and appends the options and arguments defined in _CL_,
before processing.

The Compiler switch to generate the .xdc files is /doc

You could then run XDCMAKE on the resulting .xdc files.

Ideo