- 浏览: 225391 次
- 性别:
- 来自: 北京
文章分类
最新评论
-
synack:
写的很好,图文并茂,语言简单清晰,赞!
SkipList 跳表 -
king_c:
jiandandecaicai 写道你好,请教一下是如何通过E ...
从Hadoop URL 中读取数据 -
jiandandecaicai:
你好,请教一下是如何通过Eclipse来连接Hadop机群的, ...
从Hadoop URL 中读取数据
一.摘要
在本系列的第一篇文章介绍了.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
发表评论
-
openface 人脸识别开放平台
2014-08-10 17:27 1783using System; using System.Co ... -
新中新二代身份证dll调用,报尝试读取或写入受保护的内存,这通常指示其他内存已损坏 这个错
2014-06-26 04:04 916新中新二代身份证dll调用问题: ... -
【OpenCV学习笔记】2.3 OpenCV2.2摄像头读取视频的问题和解决(VS2010)
2014-06-18 16:38 3948摄像头读取视频这一块研究了很长时间,终于弄好了。刚开始 ... -
C# 4.0 并行计算部分 [转发]
2014-05-03 15:24 1065沿用微软的写法,System.Threading.Task ... -
vector 转换成 数组 - [C++]
2013-12-13 18:06 4737参考: http://topic.csdn.n ... -
convert file into byte array
2012-05-12 23:16 928private byte [] StreamFile(s ... -
C#访问和操作MYSQL数据库
2012-03-23 09:59 1614这里介绍下比较简单的方式,引用MySql.Data.dll ... -
C#访问和操作MYSQL数据库
2012-03-23 09:58 1这里介绍下比较简单的方式,引用MySql.Data.dll ... -
http://www.microsoft.com/china/MSDN/library/langtool/VCSharp/USgetstart_vcsharp.
2012-03-22 21:26 1208http://www.microsoft.com/china/ ... -
使用Signature Tool自动生成P/Invoke调用Windows API的C#函数声明
2012-03-17 22:47 1290在网上看到很多网友在.NET程序中调用Win32 API, ... -
MarshalAs
2012-03-17 22:04 1363MarshalAs是提供向非托管代码封送数据时的规则。比如S ... -
Timeout expired. The timeout period elapsed prior ..
2012-02-26 19:13 1697关于这个问题,要 ... -
c#winform编程中获取cpu个数的方法 详细出处参考:http://www.ityoudao.com/Web/Csharp_590_1542.html
2012-02-23 18:44 978前些时间,为了配置合更加快速有效地制作Sphinx分词搜 ... -
C# socket 服务端实例
2011-12-08 19:50 1064IPAddress ipAddress; ... -
C# 文件操作
2011-12-08 19:40 763文件读取: Console.W ... -
C# 多线程处理相关说明: WaitHandle,waitCallback, ThreadPool.QueueUserWorkItem
2011-09-03 15:33 4121最近接触C#的一个项目,里面用到了多线程处理,这里做个备 ... -
c#的ThreadPool使用笔记(一)
2011-09-03 15:27 1910摘要:系列文章,从 ... -
C# 调用C++ DLL编码问题
2011-08-29 14:25 1539今天用C#调用C++写的一个DLL 死活不成功 ... -
关于global.asax 总结经验
2011-08-25 14:13 14261. 关于global.asax 总结 ... -
WebService获取服务端硬件信息和客户端IP,MAC,浏览器信息
2011-07-28 18:58 1460using System;using System.Co ...
相关推荐
本篇将深入探讨XML编程的基础概念、语法特性以及实际应用,帮助你从入门到精通。 1. XML基础: - **语法规范**:XML文档必须有且只有一个根元素,所有元素都以尖括号包围,如`<element>`,属性值需用引号包围。 -...
本篇文章将深入探讨C#与XML的结合使用,包括XML的基本概念、C#中的XML处理技术以及如何在实际项目中应用这些技能。 一、XML基础 1. XML结构:XML文档由元素、属性、文本、注释和处理指令等组成,遵循严格的规则,...
你要在DTD中定义一个元素,然后在XML文档中使用。元素的定义语法为:<!ELEMENT DESCRIPTION (#PCDATA, DEFINITION)*> 说明: "<!ELEMENT" 是元素的声明,说明你要定义的是一个元素; 声明后面的"DESCRIPTION",...
- **第31章:XML文档**:学习如何生成XML文档注释,提高代码可读性和维护性。 **32. 网络编程** - **第32章:网络编程**:探讨如何使用C#进行网络通信编程,包括套接字编程等技术。 **33. GDI+入门** - **第33章...
在.NET框架中,Language Integrated Query(Linq)是一项强大的技术,它允许开发者使用一种自然、简洁的方式来查询数据,无论数据源是数据库、XML文档还是集合。本篇文章将深入浅出地介绍Linq的基础知识,并通过实例...
2. 在集合类中使用一个预定义的集合。 (2) throw 语句用于发出在程序执行期间出现反常情况(异常)的信号。throw 语句的形式为: throw [expression]; expression :异常对象。当在 catch 子句中再次引发当前异常...
第二篇专门介绍JavaScript中内置对象的应用,内容包括JavaScript对象基础、窗口和框架、屏幕和浏览器对象、文档对象、历史对象和地址对象、表单对象和表单元素和脚本化cookie等。第三篇讲解的是JavaScript的高级技术...
第二篇专门介绍JavaScript中内置对象的应用,内容包括JavaScript对象基础、窗口和框架、屏幕和浏览器对象、文档对象、历史对象和地址对象、表单对象和表单元素和脚本化cookie等。第三篇讲解的是JavaScript的高级技术...