Sandcastle Help File Builder不识别.ascx.designer.vb中ASP.NET元素的XML注释

我之前也遇到过类似的问题，这其实不是Sandcastle的锅，是.ascx.designer.vb这类设计器文件的特殊性导致的——默认情况下SHFB不会自动处理这些文件里的部分类成员注释。给你几个可行的解决方案：

1. 把控件声明移到代码后置文件（最推荐） #

你看设计器文件里的注释都提示了：

To modify move field declaration from designer file to code-behind file.

直接把带注释的控件声明从设计器文件挪到对应的.ascx.vb（或者.aspx.vb）里就行，比如：

Partial Public Class WebUserControl
    '''<summary>
    '''TblsDiv control.
    '''</summary>
    '''<remarks>
    '''自定义备注内容——再也不用担心被VS自动覆盖啦！
    '''</remarks>
    Protected WithEvents TblsDiv As Global.System.Web.UI.HtmlControls.HtmlGenericControl
End Class

这样Sandcastle就能正常识别代码后置文件里的XML注释，生成对应的文档了。而且这么做最大的好处是，Visual Studio重新生成设计器文件的时候，不会把你写的注释搞丢。

2. 手动让SHFB包含设计器文件 #

如果你不想动代码，也可以在SHFB项目里手动添加设计器文件作为文档源：

• 打开你的SHFB项目
• 右键点击Documentation Sources，选Add
• 找到并添加对应的.ascx.designer.vb/.aspx.designer.vb文件
• 重新生成帮助文档

不过要提醒你：每次修改Web窗体或用户控件，VS都可能重新生成设计器文件，你的手动注释很容易被覆盖，所以这个方法只适合临时用用。

3. 批量处理用注释导入工具（进阶） #

如果有一大堆设计器文件要处理，可以写个脚本或者用工具自动提取这些文件里的注释，生成独立的XML注释文件，然后在SHFB里导入这个文件作为补充注释。不过这个需要点额外的开发工作，适合批量处理的场景。

总的来说，最靠谱的还是第一种方法，把控件声明移到代码后置文件里，既安全又省心。

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