How to build DocFx site via Visual Studio/Azure DevOps/TFS

[lanthonyneville]

After the docfx console was retired (DocFx 2.60.0) it took me a while to work out how to build a DocFx site via an automated Azure DevOps/TFS build. Here is how I do it. This would also work if building manually in Visual Studio.

(thanks to @KalleOlaviNiemitalo in #8412 and #8415 for tips)

Step 1: Create Visual Studio solution, containing 1 project per DocFx site

Note: the below describes manually generated Markdown-based content, but the same setup ought to work for automatically generated content describing .NET APIs.

• Create an empty Visual Studio solution
• Add a .NET C# Class Library project (.NET Framework class library might work, but below assumes latest .NET version)
• Add the Markdown content files, TOC.yml files, static resources etc
• Add the docfx.json file to the root of the project
• To publish additional DocFx sites under the same Visual Studio solution, add additional projects as above

Step 2: Add a build script (.targets file) to run DocFx and publish site

Note: in #8412 two approaches are described for running DocFx: (i) via code using Microsoft.DocAsCode.App package, and (ii) via the docfx .NET tool. The below uses the docfx .NET tool approach.

• Create a text file called DocFxBuild.targets in the root of the project (sample content and explanation below)

• Create a text file called dotnet-tools.json in the root of the project (sample content and explanation below)

• Edit the project file (i.e. .csproj) and add the following lines above the closing </Project> tag

  <Import Project="$(MSBuildProjectDirectory)\DocFxBuild.targets" />

• I also recommend adding this section, which avoids all the files generated during the build process from appearing like they belong to the project (i.e. the project only appears to contain the Markdown source etc)

  <ItemGroup>
    <None Remove="**\bin\**" />
    <None Remove="**\obj\**" />
    <None Remove="**\_Site\**" />
    <None Remove="**\*.zip" />
    <None Remove="**\*.partial" />
    <None Remove="**\*.html" />
    <None Remove="**\log.txt" />
  </ItemGroup>

Step 3: Build solution

• Test building the solution in Visual Studio. If it works, the built content (HTML files etc) should appear in a folder called _Site in the project folder.
• If building via Azure DevOps/TFS, set up a build pipeline that just builds the Visual Studio solution. No other special steps (other than Use NuGet and NuGet Restore, which are added by default I think) are needed, because the execution of DocFx is done by the .targets file, which is run by the building of the project. Example pipeline:

The DocFxBuild.targets file (build script)

This controls the execution of DocFx, and (optionally) publishing the resulting content. The script is triggered by building the project (due to the 1st edit to the .csproj file, above).

In this example, the site content is zipped and published to a network share. Other commands that can be used are described here.

Note how the Condition=... arguments are used to only run these steps when building in Release mode.

<?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <!-- Path to DocFx drop folder -->
    <DocFxDropFolder>\\server-name\share-name</DocFxDropFolder>
    <!-- Location of built DocFx content -->
    <DocFxSiteBuildFolder>$(MSBuildProjectDirectory)\_Site</DocFxSiteBuildFolder>
    <!-- DocFx content ZIP file to create  -->
    <DocFxZipFileName>$(MSBuildProjectDirectory)\DocFxSite_$(MSBuildProjectName).zip</DocFxZipFileName>
    <!-- Username and password to use when copying ZIP file -->
    <CopyAsUser>xxxxxxxxxx</CopyAsUser>
    <CopyAsUserPassword>xxxxxxxxxx</CopyAsUserPassword>
  </PropertyGroup>

  <!-- Run DocFx to generate site content -->
  <Target Name="RunDocFx" AfterTargets="Build" Condition="'$(Configuration)'=='Release'">
    <!-- Install DocFx locally (using version from dotnet-tools.json) -->
    <Exec Command="dotnet tool restore" ContinueOnError="false" />

    <!-- Run DocFx to generate content -->
    <Exec Command="dotnet tool run docfx" ContinueOnError="false" />
  </Target>

  <!-- Copy the zipped DocFx site to the drop folder -->
  <Target Name="UploadDocFxSiteToServer" AfterTargets="RunDocFx" Condition="'$(Configuration)'=='Release'">
    <!-- Create ZIP file -->
    <ZipDirectory SourceDirectory="$(DocFxSiteBuildFolder)" DestinationFile="$(DocFxZipFileName)" Overwrite="true" />

    <!-- Get handle to ZIP file -->
    <ItemGroup>
      <DocFxZipFile Include="$(DocFxZipFileName)"/>
    </ItemGroup>

    <!-- Copy ZIP file to drop folder -->
    <Exec Command="net use $(DocFxDropFolder) /delete" ContinueOnError="true" />
    <Exec Command="net use $(DocFxDropFolder) /user:$(CopyAsUser) $(CopyAsUserPassword)" ContinueOnError="false"/>
    <Copy SourceFiles="@(DocFxZipFile)" DestinationFolder="$(DocFxDropFolder)" ContinueOnError="true" />
    <Exec Command="net use $(DocFxDropFolder) /delete" ContinueOnError="true" />
  </Target>
</Project>

The dotnet-tools.json file

This controls the automatic installation of DocFx as a local .NET tool (you do not have to install DocFx manually on the machine running the build). The DocFx version to use is specified in the file, so if you want to use a later version you have to edit the file.

Note: some articles say this file has to be in a subfolder called .config, but it seems to work when in the project root folder also.

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "docfx": {
      "version": "2.64.0",
      "commands": [
        "docfx"
      ]
    }
  }
}

[michfuchs]

Awesome work, very cleanly documented - thanks!

I came here from #9225, looking for a way to keep msbuild rather than the command line to compile the site. This solution works flawlessly, and it's even an improvement over what docfx.console nuget package used to be, because with the .NET tool the build output is displayed.

My only small issue was, in DocFxBuild.targets I had to to move the PropertyGroup into Target block UploadDocFxSiteToServer, otherwise the properties were not picked up.

[lanthonyneville]

Glad it helps :) Not sure why you had to change the .targets file ... mine works exactly as shown above.