在本系列的第一篇文章介紹了.net中xml注釋的用途, 本篇文章將講解如何使用xml注釋生成與msdn一樣的幫助檔案.主要介紹ndoc的繼承者:sandcastle.
要生成幫助檔案,很多人會想到ndoc.其實在vs2003中不使用ndoc也一樣具有"生成web文件"的功能.然而很不幸,在公升級為vs2005和vs2008後, visual studio中的此功能已經取消. 更遺憾的是ndoc這個專案由於資金等問題，作者kevin於2023年7月宣布不再投入ndoc開源專案的開發，ndoc停留在1.3的歷史版本，無法完全支援.net 2.0，將漸漸淡出人們的視野。
去年我還在使用vs2003.所以生成幫助文件使用了其自帶的"生成web文件"功能, 會自動根據注釋生成html格式的幫助文件.今天我們公司已經全面公升級到了vs2008以及framework3.5,所以經過一番折騰發現居然找不到以前的這個功能了, 而且ndoc也不支援framework2.0.
經歷了一番周折,我發現了sandcastle這個由微軟開發的軟體.在此還要感謝微軟論壇的版主"周雪峰"為我指點迷津告訴我此軟體的存在.
在發布vs2005之前，ms內部開發了乙個用於生成幫助文件的工具。這就是sandcastle的前身。但是當時編譯一次文件就需要十多個小時，使得工具的可用性不強。後來隨著版本的不斷優化,現在生成乙個幫助文件大約只需要3分鐘(分鐘級別,具體時間要看生成文件的大小).
sandcastle是乙個微軟發布的工具，它通過反射程式集中的源**以及新增**中的xml注釋來建立msdn形式的api文件。 這個工具的源**可以在codeplex中以微軟公開許可協議（microsoft public license）下獲得。sandcastle 主要特性有：
有關這幾個專案的關係可以用下圖表示:
上圖中各部分的作用:
mrefbuilder使用cci從程式集中生成輸出檔案
xsltransform使用上面輸出的檔案生成 reflection.xml 文件和manifest檔案.其中reflection.xml包含所有無表現元素的資料.
build assembler可由命令列工具buildassembler啟動。它利用由mrefbuilder生成的資料(reflection.xml)和任何**注釋（儲存在獨立的xml檔案中），生成按邏輯分組的html檔案。
html help compiler(1.x , 2.0 ) 再利用這些html檔案生成最終結果。
我們注意到源**中有乙個chmbuilder, 它的作用是生成可以供html help workshop使用的.hhc一類的檔案,這些檔案都是.chm格式檔案的元資料.html help workshop的作用就是根據這些檔案生成最終文件.
本篇文章只從我所掌握的知識上,講解如何快速簡單的使用sandcastle.方法可能有些繁瑣.要想如魚得水的使用它現在看來必須要使用第三方開發的sandcastle輔助工具.在本系列以後的文章中我會抽出時間進行研究.
首先需要我們準備如下軟體:
準備好程式的dll檔案和注釋的xml檔案.比如本文例項的兩個檔案:xmlcommentclassdemo.dll 和 xmlcommentclassdemo.xml
注意如果我們的專案關聯多個dll,則需要將相關的專案的dll和注釋xml檔案都準備好.否則的話在幫助檔案中將不能點選相關的類.(如果新增了乙個類所在的專案dll和xml檔案,則此類在chm檔案中可以被點選,點選後跳轉到此類的說明頁面.)
安裝完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\ 資料夾中.
在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幫助文件生成器使用介紹
一 軟體介紹 sandcastle是乙個管理類庫的文件編譯器，是用於編譯發布元件 assembly 資訊的乙個工具，這個工具通過反射和xslt技術，可以從dll檔案及其xml注釋 命令列編譯時加 doc引數或vs2005設定專案屬性得到 得到乙個完整的幫助文件，格式可以是html或chm甚至是任何自...
Sandcastle 強大的C 文件生成工具
5.點選上面的生成選單或者按鈕，就可以直接開啟生成過程介面，在這裡可以直接檢視生成過程中的一些提示和錯誤.生成完成後，乙個和msdn風格一致的文件就出來了 6.而且支援在文件中插入，插入 等功能。7.規範是最根本的前提，一定要在 中提加足夠的注釋。資源 sandcastle help file bu...
vcbuild的簡單使用
vcbuild 命令列 更新 2007 年 11 月 vcbuild 工具使用以下命令列語法來生成 visual c 專案和解決方案。複製 vcbuild options project solution config all 標誌 options生成選項。有關更多資訊，請參見 vcbuild 選項...