SHFB项目中的C init属性访问器文档生成问题解析

背景介绍

在C# 9.0中引入了一个重要的新特性——init访问器，它允许属性在对象初始化期间被赋值，但在初始化完成后变为只读。这个特性为不可变对象的创建提供了更简洁的语法支持。

问题现象

当使用Sandcastle Help File Builder(SHFB)工具为包含init访问器的属性生成文档时，早期版本会出现一个文档生成问题：init访问器在生成的文档中被错误地显示为set访问器。例如：

// 实际代码
public int Foo { get; init; }

// 错误生成的文档显示
public int Foo { get; set; }

技术原理

这个问题的根源在于编译器对init访问器的实现方式。在底层，C#编译器会为init访问器添加一个特殊的修饰符modreq(必需修饰符)，具体是使用System.Runtime.CompilerServices.IsExternalInit类型来标记set访问器的返回类型(void)。

解决方案

在SHFB的2022.10.15.0版本中，开发团队已经修复了这个问题。新版本能够正确识别和处理init访问器，在生成的文档中准确显示init而不是错误地显示为set。

开发者建议

对于使用SHFB生成文档的项目：

1. 如果项目中使用了C# 9.0或更高版本的init访问器特性
2. 并且需要准确生成API文档
3. 应当确保使用SHFB 2022.10.15.0或更高版本

版本兼容性考虑

在升级SHFB版本时，开发者需要注意：

• 旧项目从早期版本(如2020版)升级到新版本时，可能需要调整一些配置
• 新版本不仅修复了init访问器的问题，还可能包含其他改进和bug修复
• 建议在升级前备份项目，并在测试环境中验证文档生成结果

总结

SHFB作为.NET文档生成工具，持续跟进C#语言的新特性支持。对于使用现代C#特性的项目，保持SHFB工具的最新版本是确保文档准确性的重要前提。init访问器文档生成问题的解决，体现了开源项目对语言新特性的快速响应能力。