Azure Pipeline中DocFx报Invalid cref value "!:Exception"错误求助

问题详情 #

在Azure Pipeline经典管道里使用chrismason.vsts-docfxtasks.docfx-extension-build-task.DocFxTask@0任务生成DocFx文档时，频繁出现类似Invalid cref value "!:Exception" found in triple-slash-comments for的错误，涉及Exception等标准.NET内置类型。

但在本地Visual Studio开发者终端中，直接运行docfx <MyProjectName>/docfx.json却完全正常，无任何此类错误。

已在管道中执行NuGet还原和项目构建步骤，移除构建步骤对错误输出无明显影响。所有项目基于.NET Core 8.0。

管道任务配置（YAML） #

- task: chrismason.vsts-docfxtasks.docfx-extension-build-task.DocFxTask@0
  displayName: 'Create Top Level Documentation'
  inputs:
    solution: src/<MyProjectName>/docfx.json
    docfxOptions: /Documentation/docfx.json

docfx.json配置 #

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "Project1/Project1.csproj",
            "Project2/Project2.csproj",
            "Project3/Project3.csproj"
          ],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": ".."
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "toc.yml",
          "index.md",
          "api/**.md",
          "api/**.yml",
          "api/toc.yml"
        ]
      }
    ],
    "dest": "website",
    "fileMetadataFiles": [],
    "globalMetadata": {
      "_appTitle": "???? Core Library",
      "_appName": "???? Core Library",
      "_appFooter": "Copyright ????",
      "_appFaviconPath": "resources/ico/favicon.ico",
      "_appLogoPath": "resources/png/logo.png",
      "_disableNavbar": false,
      "_disableBreadcrumb": false,
      "_disableToc": false,
      "_disableContribution": true,
      "_enableSearch": true,
      "pdf": false,
      "generatesAppendices": "true"
    },
    "globalMetadataFiles": [],
    "resource": [
      "Resources/ico/favicon.ico",
      "Resources/png/logo.png",
    ],
    "template": [
      "default",
      "modern"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

解决方法 #

方法1：替换第三方任务，手动安装并运行匹配版本的DocFx #

第三方DocFx任务可能自带的版本与本地不一致，或者管道代理环境缺少完整的.NET SDK参考程序集。改用手动安装指定版本的DocFx，确保和本地环境一致：

- task: UseDotNet@2
  displayName: 'Use .NET 8 SDK'
  inputs:
    version: '8.x'
    includePreviewVersions: false

- script: |
    dotnet tool install -g docfx --version 2.76.0 # 替换为你本地使用的DocFx版本
    docfx src/<MyProjectName>/docfx.json
  displayName: 'Generate DocFx Documentation'

方法2：修正管道任务的路径参数冲突 #

当前配置的docfxOptions参数指向的绝对路径可能在管道环境中不存在，或者与solution参数指定的配置文件冲突。移除该参数，仅保留正确的配置文件路径：

- task: chrismason.vsts-docfxtasks.docfx-extension-build-task.DocFxTask@0
  displayName: 'Create Top Level Documentation'
  inputs:
    solution: src/<MyProjectName>/docfx.json
    # 移除docfxOptions参数，避免配置冲突

方法3：确保项目构建输出完整 #

虽然移除构建步骤影响不大，但可以强制生成完整的程序集元数据，帮助DocFx正确解析类型：

- task: DotNetCoreCLI@2
  displayName: 'Build projects in Release'
  inputs:
    command: 'build'
    projects: 'src/<MyProjectName>/**/*.csproj'
    arguments: '--configuration Release'

# 之后再运行DocFx任务
- task: chrismason.vsts-docfxtasks.docfx-extension-build-task.DocFxTask@0
  displayName: 'Create Top Level Documentation'
  inputs:
    solution: src/<MyProjectName>/docfx.json

方法4：手动添加.NET标准库元数据源 #

如果DocFx无法自动识别.NET标准库的元数据，可以在docfx.json的metadata节点中添加指向.NET SDK程序集的源：

"metadata": [
  {
    "src": [
      {
        "files": [
          "Project1/Project1.csproj",
          "Project2/Project2.csproj",
          "Project3/Project3.csproj"
        ],
        "exclude": [ "**/bin/**", "**/obj/**" ],
        "src": ".."
      },
      {
        "files": [ "**/System.Private.CoreLib.dll" ],
        "src": "$(DOTNET_ROOT)/shared/Microsoft.NETCore.App/8.0.0" # 替换为对应.NET版本的路径
      }
    ],
    "dest": "api",
    "disableGitFeatures": false,
    "disableDefaultFilter": false
  }
]

注意：需要先通过UseDotNet@2任务设置$(DOTNET_ROOT)环境变量。

内容的提问来源于stack exchange，提问作者Dib