Docfx Csharp Setup

Execute these commands in the root of the project to set up the local dependency:

# Initialize a local tool manifest (if not already present)
dotnet new tool-manifest

# Install docfx locally for this specific project
dotnet tool install docfx

Step-by-Step Setup

Step 1: Enable XMLDOC Generation in .csproj

Add the DocumentationFile property to generate the XML file on every build.

For SDK-style projects (.NET 6+):

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

For legacy-style projects (.NET Framework):

<!-- Place AFTER the Configuration PropertyGroups so OutputPath is resolved -->
<PropertyGroup>
  <DocumentationFile>$(OutputPath)$(AssemblyName).xml</DocumentationFile>
</PropertyGroup>

Step 2: Handle WPF Projects (Critical)

WPF projects need special MSBuild target imports. See WPF-specific configuration.

Step 3: Create the docs/ Directory Structure

YourProject/
├── docs/
│   ├── docfx.json          # DocFX configuration
│   ├── index.md            # Landing page
│   └── toc.yml             # Top-level navigation
├── YourProject.csproj
├── CHANGELOG.md            # Optional: included in docs
└── README.md               # Optional: included in docs

Step 4: Create docs/docfx.json

See docfx.json template for the full configuration file template.

Key decisions:

• Set properties.Configuration to match your build config (usually Release)
• MUST set "pdf": true inside "globalMetadata" to enable modern Playwright-based PDF generation! Do not use pdf.default in templates.
• Include project-root .md files via the second content block (for CHANGELOG, README, etc.)

Step 5: Create docs/toc.yml

- name: Introduction
  href: ../README.md
- name: Changelog
  href: ../CHANGELOG.md
- name: API
  href: api/

Add additional markdown files from the project root as needed.

Step 6: Create docs/index.md

---
_layout: landing
---

# Your Project Name

Brief description of the project and pointers to key documentation sections.

## Quick Links

- **API Reference** — Browse the full API via the navigation bar.
- **Changelog** — See recent changes and releases.

Step 7: Add MSBuild Post-Build Target

Add this target at the bottom of your .csproj (before </Project>):

<!-- Generate documentation via DocFX after a successful build -->
<Target Name="GenerateDocFX" AfterTargets="Build">
  <Message Text="Running DocFX to generate API documentation..." Importance="high" />
  <!-- Requires 'dotnet new tool-manifest' && 'dotnet tool install docfx' to have been run! -->
  <Exec Command="dotnet docfx docs\docfx.json" />
  <!-- Copy generated PDFs with human-readable names to the project root directory -->
  <Copy SourceFiles="docs\_site\toc.pdf"
        DestinationFiles="$(MSBuildProjectDirectory)\$(AssemblyName) - Full Documentation.pdf"
        Condition="Exists('docs\_site\toc.pdf')" />
  <Copy SourceFiles="docs\_site\api\toc.pdf"
        DestinationFiles="$(MSBuildProjectDirectory)\$(AssemblyName) - API Reference.pdf"
        Condition="Exists('docs\_site\api\toc.pdf')" />
  <Message Text="PDF documentation copied to project root." Importance="high" />
</Target>

Note: This runs DocFX on every build. For large projects, consider making it conditional:

<Target Name="GenerateDocFX" AfterTargets="Build" Condition="'$(GenerateDocs)' == 'true'">

Then invoke with: dotnet build /p:GenerateDocs=true

For details on how DocFX names and places PDFs, see PDF output configuration.

Step 8: Update .gitignore

# DocFX generated site and artifacts
docs/_site/
docs/api/
docs/obj/
docs/*.docx
docfx_log.txt

# Project root PDFs
*.pdf

Step 9: Build and Verify

# SDK-style projects:
dotnet build -c Release

# Legacy .NET Framework (use Visual Studio's MSBuild):
& "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" YourProject.csproj /p:Configuration=Release /restore

# View the generated site:
uv run pyton -m http.server 8080 -d docs/_site
# Then open http://localhost:8080

IMPORTANT: Never open DocFX sites via file:/// — the JavaScript-based navigation and search will fail due to browser CORS restrictions. Always use a local HTTP server.

Quick Reference

Common Mistakes

Mistake 1: Forgetting to install DocFX locally via tool manifest

• The <Exec Command="dotnet docfx docs\docfx.json" /> build step will fail with "No executable found matching command 'dotnet-docfx'" if the project lacks a local tool manifest.
• Fix: Always run dotnet new tool-manifest and dotnet tool install docfx in the project root first.

Mistake 2: Using dotnet build for .NET Framework WPF projects

• dotnet build uses the .NET SDK MSBuild which lacks PresentationBuildTasks
• Use Visual Studio's MSBuild.exe instead for .NET Framework 4.x WPF

Mistake 2: Setting GenerateResourceUsePreserializedResources to true

• Causes MSB3822/MSB3823 errors about System.Resources.Extensions
• Set to false unless you explicitly need preserialized resources

Mistake 3: Opening _site/index.html via file:///

• DocFX modern template loads TOC and search via JavaScript Fetch
• Browsers block file:/// fetch requests (CORS)
• Always serve via python -m http.server or similar

Mistake 4: Forgetting WPF targets import

• .csproj must import Microsoft.WPF.targets after Microsoft.CSharp.targets
• Without it: InitializeComponent not found, 40+ compile errors
• See wpf-targets.md

Mistake 5: Solution file format too old

• Format Version 11.00 (VS 2010) triggers upgrade dialogs in VS 2022
• Use Format Version 12.00 with VisualStudioVersion = 17.0