使用.NET中的XML注释(二) -- 建立帮助文档入门篇

时间  2020-09-20 标签 使用 xml 注释 建立 帮助 文档 入门

一.摘要

在本系列的第一篇文章介绍了.NET中XML注释的用途, 本篇文章将讲解如何使用XML注释生成与MSDN同样的帮助文件.主要介绍NDoc的继承者:SandCastle.html

二.背景

要生成帮助文件,不少人会想到NDoc.其实在VS2003中不使用NDoc也同样具备"生成Web文档"的功能.然而很不幸,在升级为VS2005和VS2008后, Visual Studio中的此功能已经取消. 更遗憾的是NDoc这个项目因为资金等问题，做者Kevin于2006年7月宣布再也不投入NDoc开源项目的开发，NDoc停留在1.3的历史版本，没法彻底支持.NET 2.0，将渐渐淡出人们的视野。服务器

去年我还在使用VS2003.因此生成帮助文档使用了其自带的"生成Web文档"功能, 会自动根据注释生成HTML格式的帮助文档.今天咱们公司已经全面升级到了VS2008以及Framework3.5,因此通过一番折腾发现竟然找不到之前的这个功能了, 并且NDoc也不支持Framework2.0.框架

经历了一番周折,我发现了SandCastle这个由微软开发的软件.在此还要感谢微软论坛的版主"周雪峰"为我指点迷津告诉我此软件的存在.工具

在发布VS2005以前，MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。可是当时编译一次文档就须要十多个小时，使得工具的可用性不强。后来随着版本的不断优化,如今生成一个帮助文档大约只须要3分钟(分钟级别,具体时间要看生成文档的大小).post

三.SandCastle简介

在上一篇文章中的帮助文件截图都是使用SandCastle生成的,好比下面的截图:学习

SandCastle是一个微软发布的工具，它经过反射程序集中的源代码以及添加代码中的XML注释来建立MSDN形式的API文档。 这个工具的源代码能够在CodePlex中以微软公开许可协议（Microsoft Public License）下得到。SandCastle 主要特性有：优化

  • 兼容署名或未署名的注释
  • 支持范型以及.NET 2.0框架
  • 支持全部的.NET语言
  • 支持.NET Compact Framework 项目
  • 简单编译接口和Visual Studio插件

四.SandCastle工做原理

从CodePlex上下载SandCastle的源代码,打开后会找到以下项目:ui

image

有关这几个项目的关系能够用下图表示:插件

image

 

上图中各部分的做用:命令行

  • SandCastle中主要有三个组件：MrefBuilder、Build Assembler和XslTransform。
  • HTML Help 1.x compiler(hhc.exe) 或者 Microsoft Help 2.0 compiler(hxcomp.exe) 用来生成 .chm 或者 .hxs 文件
  • Help Viewer 用于查看帮助文件. 

MrefBuilder和XslTransform

MrefBuilder使用CCI从程序集中生成输出文件

XslTransform使用上面输出的文件生成 Reflection.xml 文档和Manifest文件.其中Reflection.xml包含全部无表现元素的数据.

BuildAssembler

Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。

HTML Help Compiler(1.x , 2.0 ) 再利用这些HTML文件生成最终结果。

除了上面介绍的核心的三个组件,还有一些用于生成最终文件的工具.好比 HTML Help Complier 这个角色是使用HTML Help Workshop工具完成的.HTML Help Workshop并不在SandCastle项目中,须要单独下载.要生成最终的.chm格式的文档,必须安装HTML Help Workshop.

咱们注意到源代码中有一个ChmBuilder, 它的做用是生成能够供HTML Help Workshop使用的.hhc一类的文件,这些文件都是.chm格式文件的元数据.HTML Help Workshop的做用就是根据这些文件生成最终文档.

五.快速上手SandCastle

本篇文章只从我所掌握的知识上,讲解如何快速简单的使用SandCastle.方法可能有些繁琐.要想如鱼得水的使用它如今看来必需要使用第三方开发的SandCastle辅助工具.在本系列之后的文章中我会抽出时间进行研究.

(1)准备软件

首先须要咱们准备以下软件:

SandCastle, 下载地址:
http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx
说明:
上面的链接会连接到CodePlex上的SandCastle项目的最新Release版本.其中页面上会有以下图两种下载方式:
image

请下载SandCastle.msi文件,这里包含咱们即将使用的一些好比GUI工具等.而下面的源代码zip中则不包含,从大小也能看出来.知道如何使用SVN和TFS的用户也能够从源代码服务器上获取最新的开发中的SandCastle版本,我获取了其SVN上的版本,获取后也包括所有内容和工具.

HTML Help Workshop,下载地址:
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

(2)准备项目文件

准备好程序的dll文件和注释的xml文件.好比本文实例的两个文件:XmlCommentClassDemo.dll 和 XmlCommentClassDemo.XML

注意若是咱们的项目关联多个dll,则须要将相关的项目的dll和注释xml文件都准备好.不然的话在帮助文件中将不能点击相关的类.(若是添加了一个类所在的项目dll和xml文件,则此类在chm文件中能够被点击,点击后跳转到此类的说明页面.)

(3)使用GUI生成帮助文件元数据

安装完SandCastle后,会在其generic目录中找到GUI工具:SandcastleGui.exe,运行界面如图:

image

如上图所示,在Name处输入"XmlCommentDemo"后,点击Build,首先会提示保存一个sproj文件.

默认会在建立文件夹: C:\Program Files\Sandcastle\\Examples\XmlCommentDemo

通过SandCastle咱们已经生成了chm文件的元数据文件,路径保存在:

C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中.

(4)使用HTML Help Workshop生成CHM文件

在C:\Program Files\Sandcastle\Examples\XmlCommentDemo\vs2005\chm\ 文件夹中有这三个文件:

XmlCommentDemo.hhc

XmlCommentDemo.hhk

XmlCommentDemo.hhp

运行HTML Help Workshop,能够打开XmlCommentDemo.hhp文件.单开文件后,单击"File"->"Compile...",弹出以下图的界面:

image

单击"Compile",则会在.hhp的目录下生成.chm文件,以下图所示:

image

XmlCommentDemo.chm就是最终文档.

五.总结

通过本篇文章的介绍将使用.NET注释的XML格式文件和程序的DLL文件,生成相似MSDN的文档.对于注释在帮助文档中的做用,请查看本系列的第一篇文章.

因为研究有限我目前也只能粗略的使用SandCastle,后续文章中将陆续深刻的学习SandCastle的使用.但愿你们可以一块儿讨论,一块儿研究,一块儿进步.

六.相关资源

微软SandCastle博客: http://blogs.msdn.com/sandcastle/default.aspx

SandCastle项目:http://www.codeplex.com/Sandcastle

 

出处：http://www.cnblogs.com/zhangziqiu/archive/2009/01/31/XmlComment-SandCastle-1.html

联系我们 沪ICP备13005482号-10