Use when adding automated API documentation to a C# project with DocFX, configuring XMLDOC generation in .csproj files, or setting up documentation pipelines for .NET Framework or .NET SDK projects.
Automate API documentation generation for any C# project using DocFX with proper XMLDOC, MSBuild integration, and a searchable documentation site.
<DocumentationFile>) in a .csprojdocfx.json for metadata extraction and site buildingNOT for:
DocFX MUST be installed locally in the target project via a .NET tool manifest. Do NOT rely on a globally installed DocFX instance, as the MSBuild execution command will fail without a local manifest.
dotnet docfxExecute 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
.csprojAdd 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>
WPF projects need special MSBuild target imports. See WPF-specific configuration.
docs/ Directory StructureYourProject/
├── 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
docs/docfx.jsonSee docfx.json template for the full configuration file template.
Key decisions:
properties.Configuration to match your build config (usually Release)"pdf": true inside "globalMetadata" to enable modern Playwright-based PDF generation! Do not use pdf.default in templates..md files via the second content block (for CHANGELOG, README, etc.)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.
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.
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.
.gitignore# DocFX generated site and artifacts
docs/_site/
docs/api/
docs/obj/
docs/*.docx
docfx_log.txt
# Project root PDFs
*.pdf
# 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.
| Task | Where |
|---|---|
| Enable XML comments | <GenerateDocumentationFile> in .csproj |
| DocFX config | docs/docfx.json |
| Navigation structure | docs/toc.yml |
| Landing page | docs/index.md |
| Post-build automation | <Target Name="GenerateDocFX"> in .csproj |
| PDF output & naming | See pdf-output.md |
| WPF-specific fixes | See wpf-targets.md |
| Full docfx.json template | See docfx-template.md |
Mistake 1: Forgetting to install DocFX locally via tool manifest
<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.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 PresentationBuildTasksMSBuild.exe instead for .NET Framework 4.x WPFMistake 2: Setting GenerateResourceUsePreserializedResources to true
System.Resources.Extensionsfalse unless you explicitly need preserialized resourcesMistake 3: Opening _site/index.html via file:///
file:/// fetch requests (CORS)python -m http.server or similarMistake 4: Forgetting WPF targets import
.csproj must import Microsoft.WPF.targets after Microsoft.CSharp.targetsInitializeComponent not found, 40+ compile errorsMistake 5: Solution file format too old
Format Version 11.00 (VS 2010) triggers upgrade dialogs in VS 2022Format Version 12.00 with VisualStudioVersion = 17.0