CODEWITHSUNDEEP
msbuild
Juan Zamudio
Juan Zamudio

Reputation: 489

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

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

Upvotes: 11

Views: 6396

Answers (3)

trindflo
trindflo

Reputation: 349

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.

Upvotes: 0

Gabor
Gabor

Reputation: 3246

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.

Upvotes: 5

KMoraz
KMoraz

Reputation: 14164

  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)) Compile the Project

  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) Run MSBuild for Project

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

Upvotes: 2

Related Questions