当我在 Azure 管道上运行时,DocFx 遇到问题,其中 DocFx 报告Invalid cref value "!:Exception" found in triple-slash-comments for
此问题和许多标准 .net 对象。
这只会发生在 Azure 管道上,如果我docfx <MyProjectName>/docfx.json
在 Visual Studio 开发人员终端中本地运行则不会发生。
我正在使用经典管道和Create DocFx Documentation
任务类型。
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
我正在使用 NuGet 恢复项目并在上一步中构建项目,尽管如果我删除构建步骤,它对构建文档的输出不会产生太大影响。
<MyProjectName>
为了使其成为公开帖子,我已将项目名称替换为。
该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
}
}
项目都是.NetCore 8.0
我可以重现这个问题。在我的测试中,管道中的“无效的 cref 值...”只是一个警告,而不是错误,并且它不会影响任务的成功运行。
这些警告与 docfx 的版本有关。使用“创建 DocFx 文档”任务时,它将
2.59.4
默认下载带有版本的 docfx。2.77.0
要解决此警告,您可以在命令行中下载最新版本的 docfx并docfx
直接运行,而不是使用“创建 DocFx 文档”任务。例如,