使用.NET中的XML註釋(二) -- 建立幫助文檔入門篇

一.摘要

在本系列的第一篇文章介紹了.NET中XML註釋的用途, 本篇文章將講解如何使用XML註釋生成與MSDN同樣的幫助文件.主要介紹NDoc的繼承者:SandCastle.

二.背景

要生成幫助文件,不少人會想到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分鐘(分鐘級別,具體時間要看生成文檔的大小).

三.SandCastle簡介

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

SandCastle是一個微軟發佈的工具，它經過反射程序集中的源代碼以及添加代碼中的XML註釋來建立MSDN形式的API文檔。 這個工具的源代碼能夠在CodePlex中以微軟公開許可協議（Microsoft Public License）下得到。SandCastle 主要特性有：

• 兼容署名或未署名的註釋
• 支持範型以及.NET 2.0框架
• 支持全部的.NET語言
• 支持.NET Compact Framework 項目
• 簡單編譯接口和Visual Studio插件

四.SandCastle工做原理

從CodePlex上下載SandCastle的源代碼,打開後會找到以下項目:

有關這幾個項目的關係能夠用下圖表示:

 

上圖中各部分的做用:

• 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版本.其中頁面上會有以下圖兩種下載方式:

請下載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,運行界面如圖:

如上圖所示,在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...",彈出以下圖的界面:

單擊"Compile",則會在.hhp的目錄下生成.chm文件,以下圖所示:

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