.NET API Docs

Docfx converts XML documentation comments into rendered HTML documentations.

Generate .NET API Docs

To add API docs for a .NET project, add a metadata section before the build section in docfx.json config:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api"
  },
  "build": {
    "content": [{
      "files": [ "api/*.yml" ]
    }]
  }
}

Docfx generates .NET API docs in 2 stages:

  1. The metadata stage uses the metadata config to produce .NET API YAML files at the metadata.dest directory.

  2. The build stage transforms the generated .NET API YAML files specified in build.content config into HTML files.

These 2 stages can run independently with the docfx metadata command and the docfx build command. The docfx root command runs both metadata and build.

Note

Glob patterns in docfx currently does not support crawling files outside the directory containing docfx.json. Use the metadata.src property

Docfx supports several source formats to generate .NET API docs:

Generate from assemblies

When the file extension is .dll or .exe, docfx produces API docs by reflecting the assembly and the side-by-side XML documentation file.

This approach is build independent and language independent, if you are having trouble with msbuild or using an unsupported project format such as .fsproj, generating docs from assemblies is the recommended approach.

Docfx examines the assembly and tries to load the reference assemblies from within the same directory or the global systems assembly directory. In case an reference assembly fails to resolve, use the references property to specify a list of additional reference assembly path:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "references": [
      "path-to-reference-assembly.dll"
    ]
  },
}

Features that needs source code information such as "Improve this doc" and "View source" is not available using this approach.

Generate from projects or solutions

When the file extension is .csproj, .vbproj or .sln, docfx uses MSBuildWorkspace to perform a design-time build of the projects before generating API docs.

In order to successfully load an MSBuild project, .NET Core SDK must be installed and available globally. The installation must have the necessary workloads and components to support the projects you'll be loading.

Run dotnet restore before docfx to ensure that dependencies are available. Running dotnet restore is still needed even if your project does not have NuGet dependencies when Visual Studio is not installed.

To troubleshoot MSBuild load problems, run docfx metadata --logLevel verbose to see MSBuild logs.

Docfx build the project using Release config by default, additional MSBuild properties can be specified with properties.

If your project targets multiple target frameworks, docfx internally builds each target framework of the project. Try specify the TargetFramework MSBuild property to speed up project build:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "properties": {
      "TargetFramework": "net6.0"
    }
  },
}

Generate from source code

When the file extension is .cs or .vb, docfx uses the latest supported .NET Core SDK installed on the machine to build the source code using Microsoft.NET.Sdk. Additional references can be specified in the references config:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "references": [
      "path-to-reference-assembly.dll"
    ]
  },
}

Supported XML Tags

Docfx supports Recommended XML tags for C# documentation comments.

Warning

Docfx parses XML documentation comment as markdown by default, writing XML documentation comments using markdown may cause rendering problems on places that do not support markdown, like in the Visual Studio intellisense window.

To disable markdown parsing while processing XML tags, set shouldSkipMarkup to true:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "shouldSkipMarkup": true
  }
}

Filter APIs

Docfx hides generated code or members marked as [EditorBrowsableAttribute] from API docs using filters. The default filter config contains common API patterns to exclude from docs.

To add additional filter rules, add a custom YAML file and set the filter property in docfx.json to point to the custom YAML filter:

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "filter": "filterConfig.yml" // <-- Path to custom filter config
  }
}

The filter config is a list of rules. A rule can include or exclude a set of APIs based on a pattern. The rules are processed sequentially and would stop when a rule matches.

Filter by UID

Every item in the generated API docs has a UID (a unique identifier calculated for each API) to filter against using regular expression. This example uses uidRegex to excludes all APIs whose uids start with Microsoft.DevDiv but not Microsoft.DevDiv.SpecialCase.

apiRules:
- include:
    uidRegex: ^Microsoft\.DevDiv\.SpecialCase
- exclude:
    uidRegex: ^Microsoft\.DevDiv

Filter by Type

This example exclude APIs whose uid starts with Microsoft.DevDiv and type is Type:

apiRules:
- exclude:
    uidRegex: ^Microsoft\.DevDiv
    type: Type

Supported value for type are:

  • Namespace

  • Class

  • Struct

  • Enum

  • Interface

  • Delegate

  • Event

  • Field

  • Method

  • Property

  • Type: a Class, Struct, Enum, Interface or Delegate.

  • Member: a Field, Event, Method or Property.

API filter are hierarchical, if a namespace is excluded, all types/members defined in the namespace would also be excluded. Similarly, if a type is excluded, all members defined in the type would also be excluded.

Filter by Attribute

This example excludes all APIs which have AttributeUsageAttribute set to System.AttributeTargets.Class and the Inherited argument set to true:

apiRules:
- exclude:
  hasAttribute:
    uid: System.AttributeUsageAttribute
    ctorArguments:
    - System.AttributeTargets.Class
    ctorNamedArguments:
      Inherited: "true"

Where the ctorArguments property specifies a list of match conditions based on constructor parameters and the ctorNamedArguments property specifies match conditions using named constructor arguments.