Sandcastle CHM 编译 BAT 脚本和配置实用程序

• 下载演示 - 9.73 Kb
• 下载源代码 - 12.7 Kb

引言

Sandcastle 是 Microsoft 用于从 .NET 程序集和代码内 XML 注释生成 MSDN 风格文档的新工具。更多信息请点击此处^。2006 年 7 月 29 日，他们发布了 CTP 版本，博客也很快跟进了使用其测试类生成 CHM 文件的 11 步手动流程。创建 BAT 脚本来自动完成所有这些工作似乎很容易，但是，有几个问题使得这并非易事。我已经开发了一个 BAT 脚本来自动化此过程，以及一个配置工具。

优点

• 支持多个程序集。
• 当您需要重新编译文档时，只需重新运行 BAT 脚本（无需运行 GUI 并重新选择程序集/注释文件）。
• 如果帮助项目存在，则不会覆盖（这样您就可以在帮助工作坊中修改它 - 特别方便设置默认页面，以免打开 CHM 时出现感叹号图标）。
• 编译 CHM 后选择保留或删除工作文件的选项。
• 配置工具会在您选择程序集时自动填写 XML 路径和 CHM 路径。（前提是 XML 文件存在且 CHM 字段为空。）

缺点

• BAT 脚本没有很好的日志记录、友好的消息或错误处理。

配置工具

浏览您的 .NET 程序集。如果存在同路径的 XML 文件，XML 路径会自动设置。CHM 路径也会使用相同路径自动设置，除非您已经指定了 CHM 路径。如果您勾选了“删除工作文件”复选框，“output”文件夹（包含 HTML 帮助项目、HTML 文件、艺术文件等）将被批量脚本删除。

点击“创建 BAT”，这将自定义 BAT 脚本并将其保存到您为 CHM 文件选择的相同文件夹中（文件名：sc_compile.bat）。同时，自定义的 sandcastle.config 文件也将保存到此文件夹（根据 template.xml 中的手动设置提供正确的路径）。现在，只需双击 sc_compile.bat 并等待它发挥作用。您应该会得到您指定的 CHM 文件。

注意：如果您愿意，可以移动 sc_compile.bat 和 sandcastle.config 到另一个文件夹 - BAT 脚本可以从任何地方运行。运行时，它会创建一个 output 文件夹，所有工作文件都在那里生成/复制。如果您在配置工具中勾选了复选框，则在 CHM 编译完成后，该文件夹会自动删除。

这个 template.xml 是什么？

嗯，对于简单的模板转换，我并不喜欢 XSLT。而且 String.Format() 带有各种 {0}..{n} 散布在源字符串中，这会非常令人困惑。几年前，我创建了一个类来通过处理对应于元素名称的替换变量来执行替换。

在 template.xml 中，您可以编辑两个不可编辑的设置。它们是：SandCastleInstallPath 和 HtmlHelpInstallPath。如果您为 Sandcastle 或 HTML Help 选择不同的安装路径，则需要手动更改这些值。

来自 template.xml 的两小段摘录

<AssemblyPath>C:\test_sc\assembly here\ScrollingGrid.dll</AssemblyPath>
<XmlCommentsPath>C:\test_sc\assembly here\ScrollingGrid.xml</XmlCommentsPath>
MRefBuilder "{$AssemblyPath$}" /out:reflection.org
copy "{$XmlCommentsPath$}" comments.xml

正如您所猜到的，{$AssemblyPath$} 会被 AssemblyPath 节点的文本替换。执行此替换功能的类包含在源代码中。

要求

1. Sandcastle
2. HTML Help 1.4 SDK
3. .NET Framework 2.0

BAT 脚本

这是 BAT 脚本的最新版本

为避免页面滚动，代码片段中的文本已换行。

if not exist output mkdir output
cd output
if not exist comments mkdir comments
del comments\*.xml
copy "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.xml" comments
MRefBuilder "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.*" 
            /out:reflection.org
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl" 
             reflection.org | XslTransform "C:\Program Files\Sandcastle\
             ProductionTransforms\AddGuidFilenames.xsl" 
             /out:reflection.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
              ReflectionToManifest.xsl"  reflection.xml 
              /out:manifest.xml
if not exist html mkdir html
if not exist art mkdir art
if not exist scripts mkdir scripts
if not exist styles mkdir styles
copy "C:\Program Files\Sandcastle\Presentation\art\*" art
copy "C:\Program Files\Sandcastle\Presentation\scripts\*" scripts
copy "C:\Program Files\Sandcastle\Presentation\styles\*" styles
BuildAssembler /config:../sandcastle.config manifest.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
             ReflectionToChmContents.xsl" reflection.xml 
             /arg:html="html" /out:"Test.hhc"
if not exist help_proj.hhp copy "C:\Program Files\Sandcastle\
       Presentation\Chm\test.hhp" help_proj.hhp
"C:\Program Files\HTML Help Workshop\hhc.exe" "%CD%\help_proj.hhp"
@copy "Test.chm" "..\doc.chm"
@cd ..
REM @rd /s /q output
@pause

正如您所见，所有路径都已配置。开发过程中棘手的部分是弄清楚 sandcastle.config 需要哪些自定义设置才能找到其程序集和 XML 文件，并将 HTML 文件生成到正确的目录。当时没有关于这方面的信息，也没有关于参数的文档。

注意：Sandcastle 安装会将 C:\Program Files\Sandcastle\ProductionTools 添加到 Windows PATH 环境变量中。但是，如果您在使用 MRefBuilder、XslTransform 和 BuildAssembler 时遇到问题，可以将这些调用转换为绝对路径（只需更新 template.xml）。

结论

我认为 Microsoft 在生成的 HTML 文件界面方面做得很好（例如，DHTML 功能等），这正是我对这个版本最感兴趣的地方。我还没见过其他文档编译器生成的高质量 MSDN 风格文档 - 但我必须承认我还没试过最新版本的 NDOC。

更新

• 打开输出目录的链接标签。（2006 年 8 月 5 日）
• 现在支持**通配符**（即，同一 CHM 文件中多个程序集的类文档）。正如您在截图中所看到的，只需指定 *.* 作为程序集文件，*.xml 作为您的注释文件。BAT 脚本和 sandcastle.config 已更新以支持此功能，并且对我来说运行良好。（2006 年 8 月 2 日）