解决DocFX与Roslyn源码生成器结合时属性类缺失问题

问题背景

在使用DocFX进行.NET项目文档生成时，当项目中使用了Roslyn源码生成器(Source Generators)生成的属性类(Attribute)时，会遇到编译错误。具体表现为DocFX无法识别由源码生成器动态生成的属性类，导致文档生成过程失败。

错误现象

典型错误信息如下：

MyClass.cs(11,6): error CS0246: The type or namespace name 'ElementFactoryAttribute' could not be found (are you missing a using directive or an assembly reference?)

这种错误发生在项目中使用类似如下代码时：

[ElementFactory]
public class MyClass
{
    // 类实现
}

问题原因分析

DocFX在生成文档时，会通过MSBuildWorkspace以Release配置构建项目。但这一过程存在两个关键问题：

1. 物理DLL文件缺失：DocFX的构建过程不会生成物理DLL文件，导致项目分析器被解析为UnresolvedAnalyzerReference。

2. 源码生成被跳过：由于上述原因，源码生成过程被静默跳过，导致动态生成的属性类无法被识别。

解决方案

经过验证，可以通过以下步骤解决此问题：

1. 首先手动执行Release构建：

dotnet build -c Release

2. 然后执行DocFX元数据生成：

docfx metadata

3. 最后生成完整文档：

docfx docfx.json

技术原理

这种解决方案有效的根本原因在于：

1. 手动构建生成必要文件：dotnet build命令会完整执行构建流程，包括源码生成器的工作，生成所有必要的中间文件和程序集。

2. DocFX复用构建结果：后续的DocFX命令可以复用已经生成的构建结果，避免了在自身构建过程中源码生成器失效的问题。

最佳实践建议

对于使用Roslyn源码生成器的项目，建议：

1. 在CI/CD流程中，明确区分构建和文档生成阶段。

2. 文档生成前确保项目已成功构建。

3. 考虑使用脚本自动化这一流程，避免手动操作遗漏。

总结

DocFX作为.NET生态中优秀的文档生成工具，在与Roslyn源码生成器等现代.NET特性配合使用时，需要注意构建顺序的特殊要求。通过先构建后生成文档的流程，可以确保动态生成的代码能够被正确识别和处理，从而生成完整的项目文档。