博客园_皮皮虾

.NET中锁6大处理方法[转]

2012-01-13T09:44:00Z

本文介绍了处理.NET中锁的6种方法，首先我们讨论一下并发性问题，然后讨论处理乐观锁的3种方法，乐观锁不能从根源上解决并发问题，因此后面我们介绍了悲观锁，最后介绍隔离级别如何帮助我们实现悲观锁，每个隔离级别都列举了示例进行说明，使得概念更加清晰。

我们为什么需要锁?

在多用户环境中，在同一时间可能会有多个用户更新相同的记录，这就会产生冲突，这个就是著名的并发性问题。

　　图 1 并行性问题漫画

　如何解决并发性问题?

借助正确的锁定策略可以解决并发性问题，资源被锁定后，其它进程想要访问它就会被阻止。

并发会造成什么样的冲突?

并发主要会导致四种常见的问题，详细情况请看下表。

问题	简要描述	解释
脏读取	当一个事务读取其它完成一半事务的记录时，就会发生脏读取	用户A和用户B看到的值都是5 用户B将值修改为2 用户A看到的值仍然是5，这时就发生了脏读取
不可重复读取	在每次读数据时，如果你获得的值都不一样，那表明你遇到了不可重复读取问题	用户A看到的值是5 用户B将值改为2 用户A刷新后看到的值仍然是5，这时就发生了不可重复读取
虚幻行	如果update和delete SQL语句未对数据造成影响，很可能遇到了虚幻行问题	用户A将所有值从5修改为2 用户B使用值2插入一个新记录用户A查询所有值为2的记录，但却找不到，这时就发生了虚幻行
更新丢失	一个事务的更新覆盖了其它事务的更新结果，就是所谓的更新丢失	用户A将所有值从5更新为2 用户B将所有值从2更新到5 用户A丢失了他的更新

　　如何解决上述冲突?

答案是使用乐观锁或悲观锁，下面将进一步进行阐述。

　　图 2 乐观锁和悲观锁　

什么是乐观锁?

顾名思义，乐观锁假设多个事务相互不会影响对方，换句话说就是，在乐观锁模式下，没有锁操作会得到执行，事务只是验证是否有其它事务修改数据，如果有则进行事务回滚，否则就提交。

　图 3 乐观锁

　　乐观锁是如何工作的?

实现乐观锁的方法有多种，但基本原则都一样，总是少不了下面五个步骤：

• 记录当前的时间戳

• 开始修改值

• 在更新前，检查是否有其他人更新了值(通过检查新旧时间戳实现)

• 如果不相等就回滚，否则就提交

　　图 4 乐观锁的工作原理

　　实现乐观锁的解决方案

在.NET中，实现乐观锁的方法主要有三种：

• 数据集(Dataset)：数据集是实现乐观锁的默认方法，在更新前它会检查新旧值。

• 时间戳数据类型(timestamp)：在你的表中创建一个timestamp数据类型，在更新时，检查旧时间戳是否等于新时间戳。

• 直接检查新旧值：在更新时检查旧值和新值是否相等，如果不相等就回滚，否则就提交。

解决方案1：数据集

正如前面所说的，数据集是处理乐观锁的默认方法，下面是一个简单的快照，在Adapter的update函数上有一个调试点，当我移除断点运行update函数时，它抛出如下图所示的并行异常错误。

　　图 5 Update函数执行时抛出的异常错误

如果你运行后端分析器，你将会看到更新语句检查当前值和旧值是否相等：

exec sp_executesql N'UPDATE [tbl_items] SET [AuthorName] = @p1 WHERE (([Id] = @p2) AND ((@p3 = 1 AND [ItemName] IS NULL)
OR ([ItemName] = @p4)) AND ((@p5 = 1 AND [Type] IS NULL)
OR ([Type] = @p6)) AND ((@p7 = 1 AND [AuthorName] IS NULL)
OR ([AuthorName] = @p8)) AND ((@p9 = 1 AND [Vendor] IS NULL)
OR ([Vendor] = @p10)))',N'@p1 nvarchar(11),@p2 int,@p3
int,@p4 nvarchar(4),@p5 int,@p6 int,@p7 int,@p8 nvarchar(18),@p9 int,@p10 nvarchar(2)',@p1=N'this is new',@p2=2,@p3=0,@p4=N'1001',@p5=0,@p6=3,@p7=0,@p8=N'This is Old
Author',@p9=0,@p10=N'kk'

在这种情况下，我尝试将“AuthorName”字段值修改为“This is new”，但更新时会检查旧值“This is old author”，下面是比较旧值的精简代码段：

,@p8=N'This is Old Author'

解决方案2：使用timestamp数据类型

SQL Server有一个数据类型是timestamp，它是实现乐观锁的另一种途径，每次更新SQL Server数据时，时间戳会自动产生一个唯一的二进制数值，时间戳数据类型可用来版本化你的记录更新。

　图 6 timestamp数据类型

为了实现乐观锁，首先需要取得旧的时间戳值，在更新时检查旧的时间戳值是否等于当前时间戳，如：

update tbl_items set itemname=@itemname where CurrentTimestamp=@OldTimeStamp

然后检查是否发生了更新操作，如果没有发生更新，则使用SQL Server的raiserror产生一系列错误消息。

if(@@rowcount=0)
begin
raiserror('Hello some else changed the value',16,10)
end

如果发生了并发冲突，当你如下图所示这样调用ExecuteNonQuery时，你应该会看到错误传播。

　　图 7 时间戳发生变化，存储过程产生了错误

　　解决方案3：检查旧值和新值

许多时候，我们只需要检查相关字段值的一致性，其它字段则可以忽略，在update语句中，我们可以直接做这种比较。

update tbl_items set itemname=@itemname where itemname=@OldItemNameValue

但使用乐观锁似乎没有完全解决问题，使用乐观锁只能检查并发性问题，为了从根源上解决并发性问题，我们需要使用悲观锁，因此乐观锁能起到预防作用，而悲观锁则能治愈。

　什么是悲观锁?

悲观锁总是假定会发生并发性/冲突问题，因此会先对记录上锁，然后再更新。

图 8 悲观锁

　　如何处理悲观锁?

我们可以在SQL Server存储过程中指定IsolationLevel(隔离级别)，ADO.NET级别或使用事务范围对象处理悲观锁。

　　使用悲观锁可以获得什么样的锁?

使用悲观锁可以获得四种类型的锁：共享(Shared)、独占(Exclusive)，更新(Update)和意图(Intent)，前两个是真实的锁，后面两个是锁和标记的混合。

	何时使用	允许读	允许写
共享锁	当你只想读，不希望其它事务进行更新时	是	否
独占锁	当你想修改数据，同时不希望别人可以读，直到你更新完毕时	否	否
更新锁	这是一个混合锁，当你执行的更新操作有多个步骤时使用
	读阶段	是	否
	操作阶段	是	否
	更新阶段	否	否
意向锁（请求锁）	意向锁是分级的，当你想锁定下级资源时使用，例如，在表上的一个共享意向锁意味着共享锁是针对页面和表中的行的，	不适用	不适用
模式锁	当你修改表结构时使用	否	否
大数据块更新锁	当你执行大数据块更新时使用	表级（否）	表级（否）

　详解让人困惑的更新锁

其它锁都好理解，唯独更新锁让人迷糊，因为它混合了锁和标记，在更新前我们首先要读取记录，在读取期间锁是共享的，而在真正更新时，我们需要独占锁，更新锁是非常短暂的。

　图 9 更新时用到的几种锁

不同隔离级别之间的差异，以及何时使用它们

有4种事务隔离级别，下表列出了这4种隔离级别及其使用时间。

隔离级别	读	更新	插入
读未提交的	读取未提交的数据	允许	允许
读已提交的（默认）	读取已提交的数据	允许	允许
重复读	读取已提交的数据	不允许	允许
序列化	读取已提交的数据	不允许	不允许

　如何指定隔离级别?

隔离级别是关系数据库的一个功能，也就是说，它基本上只与SQL Server相关，而与ADO.NET，EF或LINQ是没有什么关系的，但你可以在这些组件上设置隔离级别。

图 10 隔离级别

中间层：在中间层，你可以使用事务范围对象指定隔离级别。

TransactionOptions TransOpt = New TransactionOptions();
TransOpt.IsolationLevel = System.Transactions.IsolationLevel.ReadCommitted;
using(TransactionScope scope = new
TransactionScope(TransactionScopeOption.Required, TransOptions))
{

ADO.NET：在ADO.NET中你可以使用SqlTransaction对象指定事务隔离级别。

SqlTransaction objtransaction =
objConnection.BeginTransaction(System.Data.IsolationLevel.Serializable);

SQL Server：你也可以在TSQL中使用“SET TRANSACATION ISOLATION LEVEL”指定隔离级别。

SET TRANSACTION ISOLATION LEVEL READ COMMITTED;

事务隔离级别与它能解决的并发性问题之间的对应关系

	读已提交的	重复读	序列化	读未提交的
脏读取	能解决	能解决	能解决	不能
丢失更新	不能	能解决	能解决	不能
非重复读	不能	能解决	能解决	不能
幻想行	不能	不能	能解决	不能

　解决方案4：使用“读已提交的”解决“脏读取”问题

关于“读已提交的”的一些关键点：

• 它是SQL Server默认的事务隔离级别。

• 它只读取已提交的数据，换句话说就是，任何未提交的数据它都会置之不理，直到数据提交为止，下图对其进行了详细解释，你也可以看到更新。

　　图 11 读已提交模式解析

如果你想看到上图所述的情况，只需要按照下面的步骤做就可以了：

• 打开两个查询窗口，执行一个更新事务，但不提交;

• 在第二个窗口中执行查询时，会显示如下图所示的查询被阻止的提示。

　　图 12 查询被阻止，直到更新事务提交后才能执行

“读已提交的”对立面是“读未提交的”吗?

是的，读未提交的是读已提交的对立面，当你设置读未提交的事务隔离级别时，未提交的数据也被读取了。

关于“读已提交的”关键点：

• 未提交的是可见的，因此脏读取是可能的;

• 没有锁被抓住;

• 当锁不重要时很有用，更重要的是并发性和吞吐量。

如果你也想测试一下，试试下面的SQL语句，它执行一个更新然，在等待20秒后回滚，在此期间如果你执行查询，返回的是未提交的数据，但20秒后，你再查询，返回的将会以前的旧数据，因为提交的数据已回滚。

set transaction isolation level read uncommitted
Begin Tran

Update customer set CustomerName='Changed' where CustomerCode='1001'
WAITFOR DELAY '000:00:20'
rollback tran

set transaction isolation level read uncommitted
select * from Customer where CustomerCode='1001'

　解决方案5：使用重复读解决丢失更新和非重复读

给重复读设置隔离级别后，其他人就不能读取和更新数据，关于重复读隔离级别的关键点包含：

• 当为查询设置重复事务隔离级别时，只读取已提交的数据。

• 当你使用重复读选择一条记录时，其它事务将不能更新该条记录，但查询是可以的。

• 如果在更新查询中设置了可重复事务，必须要等到事务完成才能读和更新相同的记录。

• 当选择和更新查询被设置为可重复读，其它事务可以插入新记录，换句话说就是虚幻行是可能的。

如果你想测试这个隔离级别，执行下面的语句，然后尝试查询和更新查询，它们都将被阻止，50秒后你才能看到数据。

set transaction isolation level repeatable read
Begin Tran
Update customer set CustomerName='Changed' where CustomerCode='1001'
WAITFOR DELAY '000:00:50'
rollback tran

如果在重复读模式下执行下面的查询语句，在50秒内你啥也干不了，直到事务完成后你才能得到查询结果。

set transaction isolation level repeatable read
begin tran
select * from Customer where CustomerCode='1001'
WAITFOR DELAY '000:00:50'
commit tran

注意，在此期间你可以添加CustomerCode=’1001’的新记录，换句话说就是虚幻行是可能的。

　　解决方案6：使用序列化隔离级别解决虚幻行问题

这是最高级的隔离级别，在此期间，其它事务是不能更新，查询和插入记录的，关于序列化事务的一些关键点包含：

• 当隔离级别是序列化时，没有其它事务可以插入，更新，删除或查询。

• 会出现许多阻塞，但所有并发性问题都能得到解决。

本文链接

正则表达式资源

2011-07-19T09:45:00Z

http://www.regexlib.com/ 通过这个网站可以找到很多已有的正则表达式的例子.

当用户登录网站时，一般要求用户提供登录该网站的用户名称和密码。从某种意义上说，密码的复杂程度越高，用户的信息安全性越高。因此，很多网站在注册用户信息或修改用户密码时，往往会提供一个密码强度的说明，从而提醒用户使用高强度的密码。

目前来说，密码字符可以分为3种：数字、字母和特殊字符（即除数字、字母之外的字符）。用户密码包含上述3种字符种的种类越多，密码的安全性越高。用户密码只含其中一种的安全性是最低的，如123455、abcdef等。其次是含上述2种字符的密码，如123abc、123!@#等。密码强度最好的是：包含上述3种字符，如123QAZ!@#。

注意：本小节中的特殊字符包括`、-、=、\、[、]、;、'、,、.、/、~、!、@、#、$、%、^、&、*、(、)、_、+、|、?、>、<、"、:、{和}字符。

　　1．只包含数字的密码验证

　　如果密码中只包含数字，那么该密码是非常简单。当然，它的安全性也相对较差。以下正则表达式能够验证只包含数字的密码。

\d+ （68）

该类型密码的安全性随着密码的长度增加而增加。密码长度越大，它的安全性越高。以下正则表达式能够验证长度至少为6的、只包含数字的密码。

\d{6,} （69）

　　2．只包含字母的密码验证

　　如果密码中只包含字母，那么该密码是非常简单。当然，它的安全性也相对较差。以下正则表达式能够验证只包含字母的密码。

[a-zA-Z]+ （70）

该类型密码的安全性随着密码的长度增加而增加。密码长度越大，它的安全性越高。以下正则表达式能够验证长度至少为6的、只包含字母的密码。

[a-zA-Z]{6,} （71）

　　3．只包含特殊字符的密码验证

　　如果密码中只包含特殊字符，那么该密码是非常简单。当然，它的安全性也相对较差。以下正则表达式能够验证只包含特殊字符的密码。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+ （72）

　　正则表达式（72）解释：

q \\表示字符\。

q \[表示字符[。

q \]表示字符]。

q 其他的每一个字符就表示字符本身。

　　该类型密码的安全性随着密码的长度增加而增加。密码长度越大，它的安全性越高。以下正则表达式能够验证长度至少为6的、只包含特殊字符的密码。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]{6,} （73）

　　使用工具Regex Tester测试正则表达式（73），结果如图4.34所示。

4.4.5 密码验证（2）

　　4．当且仅当含数字和字母的密码验证

　　如果密码当且仅当包含数字和字母，那么该密码的强度是中等强度。当然，它的安全性一般。以下正则表达式能够验证当且仅当包含数字和字母的密码。

[\da-zA-Z]*\d+[a-zA-Z]+[\da-zA-Z]* （74）

　　正则表达式（74）解释：

\d匹配长度至少1的、由数字组成的字符串。

[a-zA-Z]+匹配长度至少1的、由字母组成的字符串。

[\da-zA-Z]*匹配空字符串，或者长度至少1的、由数字或字母组成的字符串。

\d+[a-zA-Z]+保证密码既包含了数字又包含特殊字符。

　　使用工具Regex Tester测试正则表达式（74），结果如图所示。

　　5．当且仅当含数字和特殊字符的密码验证

　　如果密码当且仅当包含数字和特殊字符，那么该密码的强度是中等强度。当然，它的安全性一般。以下正则表达式能够验证当且仅当包含数字和特殊字符的密码。

[-\d`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]*\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[-\d`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]* （75）

　　正则表达式（75）解释：

字符类[-\d`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+：\d表示任意数字；\\表示字符\；\[表示字符[；\]表示字符]；其他的每一个字符就表示字符本身。该字符类可以匹配数字或者特殊字符。

\d+匹配最小长度为1的、由数字组成的字符串。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+匹配最小长度为1的、由特殊字符组成的字符串。

\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+保证密码既包含了数字又包含特殊字符。

　　使用工具Regex Tester测试正则表达式（75），结果如图所示。

6．当且仅当包含字母和特殊字符的密码验证

　　如果密码当且仅当包含字母和特殊字符，那么该密码的强度是中等强度。当然，它的安全性一般。以下正则表达式能够验证只包含字母和特殊字符的密码。

[-a-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]*[a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[-a-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]* （76）

　　正则表达式（76）解释：

字符类[-a-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+：a-z表示小写字母；A-Z表示大写字母；\\表示字符\；\[表示字符[；\]表示字符]；其他的每一个字符就表示字符本身。该字符类可以匹配字母或者特殊字符。

[a-zA-Z]+匹配最小长度为1的、由字母组成的字符串。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+匹配最小长度为1的、由特殊字符组成的字符串。

[a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+保证密码既包含了字母又包含特殊字符。

　　使用工具Regex Tester测试正则表达式（76），结果如图所示。

　　7．当且仅当包含数字、字母和特殊字符的密码验证

　　如果密码当且仅当包含数字、字母和特殊字符，那么该密码的强度是高强度。当然，它的安全性相对比较好。以下正则表达式能够验证当且仅当包含数字、字母和特殊字符的密码。

[-\da-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]*

(

(\d+[a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+) #数字开头

|(\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[a-zA-Z]+) #数字开头

|([a-zA-Z]+\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+) #字母开头

|([a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+\d+) #字母开头

|([-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+\d+[a-zA-Z]+) #特殊字符开头

|([-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[a-zA-Z]+\d+) #特殊字符开头

)

[-\da-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]* （77）

　　正则表达式（77）解释：

\d+匹配最小长度为1的、由数字组成的字符串。

[a-zA-Z]+匹配最小长度为1的、由字母组成的字符串。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+匹配最小长度为1的、由特殊字符组成的字符串。

\d+[a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+匹配型如“数字＋字母＋特殊字符”类型的字符串。

(\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[a-zA-Z]+)匹配型如“数字＋特殊字符＋字母”类型的字符串。

[a-zA-Z]+\d+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+匹配型如“字母＋数字＋特殊字符”类型的字符串。

[a-zA-Z]+[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+\d+匹配型如“字母＋特殊字符＋数字”类型的字符串。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+\d+[a-zA-Z]+匹配型如“特殊字符＋数字＋字母”类型的字符串。

[-`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]+[a-zA-Z]+\d+匹配型如“特殊字符＋字母＋数字”类型的字符串。

字符类[-\da-zA-Z`=\\\[\];',./~!@#$%^&*()_+|{}:"<>?]*：\d表示任意数字；a-z表示小写字母；A-Z表示大写字母；\\表示字符\；\[表示字符[；\]表示字符]；其他的每一个字符就表示字符本身。该字符类可以匹配数字、字母或者特殊字符。

　　使用工具Regex Tester测试正则表达式（77），结果如图所示。

本文链接

NDoc 用户指南(转)

2011-05-20T01:56:00Z

关于 NDoc
　NDoc 可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档，让您快速拥有专业级的类库API 文档。(VB.NET 通过第三方插件如 VBCommenter 的支持，也可以生成 XML 文档。)

　NDoc 代码文档的样式包括 HTML Help 1 (即 *.CHM 格式)，Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)，以及 MSDN 在线网页样式的 .NET Framework 类库文档。

NDoc 为开放源代码项目，采用 GNU General Public Licence 授权协议（除非您的软件/项目也采用 GPL 协议开放源代码，否则您不能在您的软件/项目中使用 NDoc 源代码中的任何部分）。更多的授权问题，请参见 GNU FAQ。

感谢您使用我们的软件，也期待着您的参与（建议、BUG 反馈、代码贡献）！

使用 NDoc 之前
请阅读 GNU General Public Licence 和 GNU FAQ。

请阅读已知问题。

请阅读必要的帮助文件编译器。

NDoc 各本地化版本
　英文版: NDoc in English
　简体中文版: NDoc in Simplified Chinese
　德文版: NDoc in German
　日文版: NDoc in Japanese
　(此列表可能并不完整。欢迎大家给我发送更多关于 NDoc 的本地化版本的网址！)

关于中文版
　此 NDoc 1.3 (中文版) 由破宝(percyboy) 翻译，遵循 GPL 协议的要求发布源代码。有关中文版的翻译问题和 bug 等，都可以通过我的博客和我联系。

NDoc 1.3 - What's new?
　NDoc 1.3 包含了大量更新和改进，也修复了许多 bug。

亮点
　NDoc 1.3 包含了许多新功能:

完全重写了 Microsoft Help 2 文档引擎，即 "VS.NET 2003 文档引擎"。
支持更多新的注释标记，如 preliminary, threadsafety 和 exclude。
支持 ObsoleteAttribute 和 FlagsAttribute 属性。
NDoc 1.3 改进了可扩展性，允许您定义自己的注释标记，并控制它们的显示样式。
用户界面更加友好。
程序集的解析及文档制作过程，在性能上有了大的提高。
与 MSDN 各帮助主题更好的共存。

VS.NET 2003 文档引擎
　新的 VS.NET 2003 文档引擎用于制作 Microsoft Help 2 形式的文档，完全按照 Microsoft 的说明，在每页头部都加入了特定的 XML 数据岛，从而和 Visual Studio .NET 2003 合并文档集合更好的兼容，和 Visual Studio .NET IDE 更好的集成(比如更好的支持“动态帮助”功能等)。

新的文档引擎可以制作出和最新 Microsoft 文档格式更为接近的文档，比如新增的语言筛选器等功能。

更多的细节请参看 VS.NET 2003 文档引擎。

性能
　所有文档引擎的性能都有很大程度的提高。

NDoc 中间 XML 数据文件的制作过程有了相当的提速，现在这个过程在整个文档生成过程中所占的时间比例已经很小了。
页面制作的时间也减少了 20% ~ 50%。
内存占用显著降低了。
命名空间层次结构页面的制作过程，得到了改进，不再担心性能或稳定性问题了。因此，文档引擎总是制作命名空间层次结构页。

程序集加载
　程序集的加载方法有了不少改进。

程序集改变时，GUI 程序不需要重新启动就能反映更新。
大多数程序集可以从网络共享地址加载。但是，因为 .NET Framework 的安全限制，由托管 C++ 生成的程序集必须在本地磁盘中，不能从网络共享地址中正常加载。
程序集的解析得到了改进，现在已经极少出错了。

国际化
　NDoc 现在可以正常处理程序集及代码注释中包含的非英文字符。除 MSDN 文档引擎(HTML Help 1 格式)之外，其他文档引擎都完全支持 Unicode (UTF-8)字符。受 HTML Help 1 的局限，MSDN 文档引擎不支持混合字符集，这是我们所无法控制的。

注意，尽管 NDoc 支持多种字符集，但 NDoc 生成的代码文档的各个标题、及 NDoc 的界面、提示消息等文本，在 NDoc 1.3 中还未实现多语言显示。

NDoc 并行运行能力
　多个 NDoc 实例现在可以同时并行运行。先前的文件锁定等问题已经得到解决。

用户界面

对拖放操作的支持。新版本中，您可以直接将程序集从资源管理器中拖曳到 NDoc GUI 的程序集列表中。
错误处理。新版本的错误处理得到了显著的改进。
帮助编译器消息。帮助编译器的消息被记入 log。如果出错，错误消息被显示出来。
属性网格。属性网格有了不少加强。
能处理程序集加载错误。
对没有 XML 文档的程序集，也能为输出简单的代码文档。
对相对路径的支持。一般都是相对于 NDoc 项目文件。

XML 文档标记
　新标记

标记	说明
<exclude/>	Directs NDoc to exclude the tagged type or member from the documentation. The tag overrides all visibility options.
<preliminary>	Marks the documentation of a type or member as preliminary. This tag can include text and block tags like <para> in order to put a custom warning into your help topics about preliminary items. If the tag is empty, preliminary topics will include the default message: [This is preliminary documentation and subject to change.] It is also possible to mark an entire help project as preliminary using the Preliminary project setting.
<devdoc>

增强的标记

标记	说明
<code>	"lang" attribute No more <include> to prevent indent "Escaped" attribute
<see>	langword

配置
　新配置项
　NDoc 1.3 加入了下面的通用配置项:

配置项

说明

文档主要配置

CleanIntermediates

是否在文档成功生成后，删除中间文件。
比如 MSDN 和 VS.NET 文档引擎会编译为单一文件，它们的中间文件包括所有编译前的网页、HTML Help 项目文件等。

FeedbackEmailAddress

用户反馈接收 Email 地址。将在输出的代码文档每页的底部添加放置指向此 Email 地址的超链接。

Preliminary

若此项为真，文档引擎将在每个页面中添加红色的消息“[此文档为预发布版本，在未来版本中有可能改变。]”。

SdkDocVersion

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪个版本的 .NET Framework SDK。

SdkDocLanguage

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪种本地化语言版本的 .NET Framework SDK。

属性(attribute)的输出

DocumentInheritedAttributes

是否输出从基类中继承而来的属性(attribute)。如果 DocumentAttributes = false，则此配置被忽略。

输出过滤

DocumentedInheritedMembers

如何输出继承的成员：可选择不输出、只输出继承的实例成员或者是全部继承成员都输出。
它有三个选项:

None	不输出继承的成员。
Instance	只输出继承的实例成员。(默认选项)
InstanceAndStatic	输出全部继承的实例和静态成员。

DocumentInheritedFrameworkMembers

是否输出从 .NET Framework 中的类、结构等继承下来的成员。(默认为输出)
注意: 如果 DocumentInheritedMembers 为 None, 此配置被忽略。

DocumentExplicitInterfaceImplementations

是否输出显式实现的接口成员。(默认为否)

DocumentSealedProtected

是否输出密封类 (sealed, VB.NET 中为 NotInheritable) 的 protected 成员。(默认为否)
注意: 如果 DocumentProtected 为 false，则忽略此项配置。

SkipNamespacesWithoutSummaries

是否跳过缺少概述信息的命名空间。(默认为否)

删除的配置项
　NDoc 1.3 删除了下面的配置项:

配置项	说明
GetExternalSumeries	NDoc 中间 XML 数据文件制作的性能有了相当的改进。因此，总是尝试为从 .NET Framework 继承而来的成员查找摘要信息。
IncludeNamespaceHierarchy	命名空间层次结构页面的制作过程，得到了改进，不再担心性能或稳定性问题了。因此，文档引擎总是制作命名空间层次结构页。

MSDN 文档引擎
　新配置项
　NDoc 1.3 为 MSDN 文档引擎加入了下面的配置项:

配置项	说明
文档主要配置
BinaryToc	是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。默认此项被设置为 true。但启用此配置项，有一些强制的限制必须满足。如果您遇到问题，可以尝试关闭此功能。更多细节请查看 HTML Help Workshop 的文档。
Title	此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。
扩展性
ExtensibilityStylesheet	用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
HTML Help 选项
AdditionalContentResourceDirectory	页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
LangID	HTML Help 文件的 LangID 设置。中文版默认为 2052。

删除的配置项
　NDoc 1.3 删除了下面的配置项:

配置项	说明
SortTOCByNamespace	在 NDoc 1.3 中，各命名空间对应的目录结点总是按字母排序。
SplitTOCs	在老的 MSDN 文档引擎中，此配置项用于克服一些限制。新版本中绕开了它。
DefaultTOC	CHM 目录中第一个命名空间结点总是被默认被选中。
LinkToSdkDocVersion	此配置项现在区分为 SdkDocVersion 和 SdkDocLanguage，且提升为所有文档引擎的通用配置项。 NDoc 1.3 仍然会尝试解析此配置，如果您重新保存，NDoc GUI 会用新的配置项改写。

改进的超链接逻辑
　<see> 将形成一个指向另一个类型/成员的文档的链接。在 NDoc 1.3 中，如果一个 HTML 页中出现了多个指向同一个类型/成员的文档的 <see>，则只转换第一个为超链接，其余的不表示为超链接、只显示为粗体。这将使页面不至于太杂乱。

HTML Help 1 目录树中的图标
　目录树中，不再出现问号(?)图标。如果没有指定，显示为空白页图标。

运算符和类型转换
　NDoc 1.3 修复了对运算符和类型转换的处理 bug，页面格式也更接近 .NET Framework SDK 类库文档。

特别的属性
　ObsoleteAttribute
　MSDN, MSDN 2003, VS.NET 2003 文档引擎，将自动为具有 ObsoleteAttribute 属性的类型/成员添加红色的提示文本。

在命名空间列表及类型的成员列表中，将为它们显示红色的“已过时。”
在类型概述页/成员页中，将为它们添加红色的“注意：此成员现已过时。”

FlagsAttribute
　如果枚举具有 FlagsAttribute 属性，MSDN, MSDN 2003, VS.NET 2003 文档引擎将自动为它们添加如下的文本:

“此枚举具有允许按位组合其成员值的 FlagsAttribute 属性。”

NDoc 1.3 的已知问题和限制

事项	说明
特别长的类型名称	NDoc 为每一个主题自动在硬盘上创建一个 HTML 文件。目前，文件名是根据完全限定名生成的。如果某类型/成员的完全限定名 (命名空间 + 类型 + 成员名) 的总字符数超过 _MAX_FNAME (256 字符)，NDoc 将无法创建这样的文件，因为操作系统不支持如此多字符的文件名。另外，文件所在完整路径的字符也不能超过 _MAX_PATH (260 字符)。如果完全限定名的字符数在 200 字符左右，那么您可能需要将 OutputDirectory 配置为一个靠近根目录的位置，这样可以避免文件的完整路径超出 260 字符。但还没有关于文件名超出 256 字符的解决方法。在未来某版本的 NDoc 中，我们会尝试解决此问题。
大小写敏感问题	文件名不是大小写敏感的，因此当 MSDN 文档引擎或者 JavaDoc 文档引擎创建 HTML 文件时，如果某些类型或成员只是在大小写上不一样，就会出现问题。请尝试避免出现这种情况。（例如：公共属性为 Thing，私有字段为 _thing, 避免出现Thing 和 thing 并行。当然，如果不输出私有字段，并行也没有问题。只是说准备输出的类型/成员不要出现这种情况。）在未来某版本的 NDoc 中，我们会尝试解决此问题。
StrongNameIdentityPermissionAttribute	标记有 StrongNameIdentityPermissionAttribute 属性的程序集，需要有特殊的密钥才能被读取。NDoc 尝试为这样的程序集生成代码文档时，会抛出异常。您可以考虑使用“条件编译”(#if...)方式为 NDoc 准备没有添加该属性的编译版本。
Compact Framework 不兼容	为 .NET Compact Framework 编译的程序集，当添加到 NDoc 项目中时，NDoc GUI 程序可能抛出异常。尤其是当该程序集引用了 Microsoft.WindowsCE.Forms 或 SqlServerCe 时，更是如此。还没有找到此问题的解决方法。在未来某版本的 NDoc 中，我们会尝试解决此问题。
本地化	NDoc 当前不支持本地化的文档格式及 GUI 文本在未来某版本的 NDoc 中，我们可能会尝试解决此问题。

开始之前，您需要准备以下工具，它们可以从网络中获得。

HTML Help 1 编译器
　HTML Help 1 文件，也就是 CHM 文件，是很常见的应用程序帮助文件格式，在 Visual Studio .NET 发布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您准备创建 HTML Help 1 (*.CHM)文件，请确认您已经安装好 Microsoft's HTML Help Workshop。此下载安装包已包含必需的 HTML Help 1 编译器。

Microsoft Help 2 编译器
　Microsoft Help 2 是 Microsoft 从 Visual Studio .NET 2002 开始使用的、一种新的帮助文档格式。

如果您准备创建 Microsoft Help 2 (*.HxS)文件，请下载并安装 Visual Studio Help Integration Kit (VSHIK)。此工具包已包含所必需的 Microsoft Help 2 编译器。

Latex 编译器
　如果您准备使用 LaTeX 文档引擎创建 dvi 或 pdf 文件，您需要下载并安装一个 LaTeX 系统，比如免费的 MikTeX。

其他工具
　H2Reg
　向客户机部署 Microsoft Help 2 帮助文档，不像 HTML Help 1 那样简单(仅复制即可完成)。VSHIK 工具包介绍了如何向客户机部署 Microsoft Help 2 帮助文档的详细步骤和指导。

另外一种方案是采用共享软件 H2Reg utility (开发商: helpware.net)。

H2Reg 许可您将它包含进部署安装包中，它可以用来注册 Microsoft Help 2 命名空间和帮助标题等。H2Reg 使用 INI 文件描述要部署的帮助文档结构。NDoc 创建符合 H2Reg 需要的 INI 文件，指示它进行命名空间的注册工作。

首先，您应该确认，您已经打开了 C# 项目的 /doc 开关，当 Visual Studio .NET 编译时，每次都会生成相应的 XML 文档。

如果没有特殊情况，请让项目输出的程序集名称和 XML 文档文件名、仅仅扩展名不同(比如程序集是 NDoc.Test.dll/NDoc.Test.exe，XML 文档是 NDoc.Test.xml)。在 NDoc 中，当您加入某程序集时，NDoc 会自动查找这样的“同名” XML 文件。如果找到，就会尝试自动将它当作该程序集的 XML 文档。这样会简化您的操作。

打开项目的“属性”对话框，

找到程序集名称

设置 XML 文档文件为程序集名称(扩展名改为 xml)。别忘了设置此项之前，选择“所有配置”，让 Debug 或 Release 配置下，都自动生成 XML 文档。

设置 XML 文档文件配置

现在，每次使用 VS.NET 编译您的程序集，都会自动从源代码中提取所有的 XML 注释，生成 XML 文档文件。

如果您使用的不是 Visual Studio .NET，您同样应该尝试打开 C# 编译器的 /doc 选项。

　The more, the better
　您在代码中书写的 XML 注释越多，最终生成的代码文档越专业。程序集的使用者越能从中获得帮助。

一般而言的最低要求，对于每一个公共类型，应该给它的所有公共的和受保护的成员添加 <summary> 注释，以描述该成员表示什么意义或者会做些什么动作。

在 VS.NET 中，C# 代码编辑器，提供了一些自动完成的功能，帮助我们创建基本的 XML 注释。

比如如下的代码:

public class MyClass() {
public MyClass( string s ) { }
}

把光标移动到 MyClass 构造函数的上面一空行，敲 '/' 键三次，VS.NET 自动创建一个 summary XML 文档块:

public class MyClass() {
/// <summary>
///
/// </summary>
/// <param name="s"></param>
public MyClass( string s ) { }
}

这种操作对于所有可以书写 XML 注释文档的成员都有效。另外，在以 '///' 开头的 XML 注释行中，敲入 '<' 字符，VS.NET 自动感知功能将自动显示可用的 XML 注释标记列表。不过，这个列表不包括 NDoc 所支持的额外的标记，这些额外的标记，您需要手工敲入。

NDoc 可以配置为输出所有的成员，包括私有的和内部的成员，虽然这些成员无法在程序集外部被调用，但如果您需要，您可以同样为这些成员添加 XML 注释，NDoc 会帮您生成这样的适合内部使用的代码文档。

NDoc 内置的 MSDN, MSDN 2003, VS.NET 文档引擎，支持 C# 程序员参考中的所有 XML 文档注释标记。

NDoc 支持扩充的标记和语法。某些标记只能用于特定的类型（类，结构，委托，接口，枚举）或成员（字段，属性，方法，事件等），请参见标记用法。

NDoc 将标记区分为三类: Section 标记，Block 标记，Inline 标记。

Section 标记
　Section 标记用于定义不同的代码文档的区域。它们都是顶级标记，Block 标记、Inline 标记都应包含在某个 Section 标记的内部。（除非自定义了扩展 XSLT 转换，否则，在 Section 标记外部的 Block 标记或 Inline 标记都被忽略。）

标记	说明
<event> [NDoc 扩充]	对某个成员可能引发的事件的说明。
<example>	“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。
<exception>	对某个成员可以抛出的异常的说明。
<exclude/> [NDoc 扩充]	指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。与文档引擎的“可见性”配置不符的，以 exclude 优先。
<include>	将代码文件外部的某 XML 文件中的一部分包含进代码文件来。
<overloads> [NDoc 扩充]	为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。 <overloads> 标记有两种形式: 简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。示例: ///<overloads>This method has two overloads.</overloads> ///<summary>This overload just says hello.</summary> public void SayHello() { ... } ///<summary>This one says hello to someone.</summary> public void SayHello(string toSomeone) { ... }
<param>	成员的参数说明。
<param>	访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。
<preliminary> [NDoc 扩充]	将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 <para> 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary
<remarks>	“备注”，对 <summary> 的进一步注解。
<returns>	“返回值”。
<seealso>	向页面的“请参见”区域添加一个链接。请不要将此标记包含在 <remarks> 内部，它是一个顶级标记。两种可选的语法: <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso> <seealso cref="System.Data.DataSet">DataSet</seealso>
<summary>	“摘要”，对类型/成员的摘要说明。
<threadsafety> [NDoc 扩充]	“线程安全”，说明类型在多线程环境中是否安全。 NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。 threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如: /// <summary>The summary description for SafeClass.</summary> /// <threadsafety static="true" instance="true"> /// <para>More information about using this class across thread</para> /// </threadsafety> public class SafeClass() { ... }
<value>	“属性值”。

Block 标记
　Block 标记用于 Section 标记的内部，它们将显示在单独的行中。

标记	说明
<code>	多行的代码块。
<list>	一个列表或表格。
<note> [NDoc 扩充]	“注意”块。例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary.
<para>	表示一个段落。

Inline 标记
Inline 标记可以用于其他 Section 标记或 Block 标记内部，它们将和前后的文本显示在同一行中。

标记	说明
<c>	将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。
<paramref>	加入指向方法参数的链接。
<see>	加入指向某个类型/成员或网络 URL 的链接。两种可选的语法: <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see> <see cref="System.Data.DataSet">DataSet</see> <see langword="xxx"/> 其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

NDoc 中的 MSDN 文档引擎和 VS.NET 文档引擎使用了一些属性来控制代码文档中一些特殊样式。

如果类型或成员具有以下属性，NDoc 将显示相应的特殊样式，使文档看起来更加专业。

属性	说明
ObsoleteAttribute	标记该类型或成员为“已过时。”
FlagsAttribute	指示可以将枚举作为位域（即一组标志）处理，允许按位组合其成员值。 NDoc 将仿照 .NET Framework SDK 文档中处理方式：在该枚举摘要下面显示“此枚举具有允许按位组合其成员值的 FlagsAttribute 属性。” 在枚举成员的列表中添加“值”列，显示每个枚举成员对应的枚举值。
EditorBrowsableAttribute	使用此属性(attribute)的成员将不显示在 VS.NET 的属性窗口、对象浏览器及智能感知等列表中，根据 NDoc 项目配置中的 EditorBrowsableFilter 配置，NDoc 可以将这部分被隐藏的成员排除在代码文档之外。注：在 NDoc 1.3 中，我们推荐您使用 <exclude/> XML 文档标记在代码文档中隐藏某些类型或成员。
AssemblyVersionAttribute	根据 NDoc 项目配置中的 AssemblyVersionInfo 配置，NDoc 可以在代码文档中包含通过 AssemblyVersionAttribute 属性指定的程序集版本信息。

新建 NDoc 项目和添加程序集
　如果您使用 Visual Studio.NET 开发工具，那么最简单的方法就是点击工具条中的“从 Visual Studio .NET 解决方案新建 NDoc 项目...”按钮。

　然后，NDoc 会要求您选择某种编译配置(如 Debug 或 Release，或者其他您自定义的编译配置)，这取决于您将使用哪种编译配置下生成的程序集和 XML 文档。

　编译配置选择对话框

“确定”之后，NDoc 项目设计器将自动生成一个新的 NDoc 项目，其中已包含解决方案中各个项目生成的程序集和相应的 XML 文档。

如果您没有使用 Visual Studio .NET，则需要手工向 NDoc 项目添加要生成代码文档的程序集和相应的 XML 文档。您可以通过点击设计器重的“添加”按钮、从文件系统中浏览并选择要添加的程序集，也可以直接从 Windows 资源管理器或“我的电脑”中、直接拖动要生成代码文档的程序集、到设计器中的程序集列表框中。

请确保您打开了 /doc 文档输出的选项，否则 NDoc 输出的代码文档只能有很少的内容。

选择文档引擎
　NDoc 内置了若干文档引擎，它们可以用于生成不同风格、样式、格式的代码文档。每种文档引擎都定义了它自己的排版、格式，以及要输出的内容。

最受欢迎的两种文档引擎是 MSDN 和 VS.NET 2003。它们都生成类似 .NET Framework SDK 类库文档样式的代码文档，不同的是前者最终编译成 HTML Help 1 （即 *.CHM）格式的整合文件，后者最终编译成 Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)格式的形式。

NDoc 1.3 中，新增了 MSDN 2003 文档引擎，在保留 MSDN 文档引擎的特点之外，向接近 .NET Framework SDK 类库文档的方向又前进了一大步：加入了语言选择器等特色功能。

NDoc 文档引擎

所有的文档引擎都共享一些配置项，比如要输出哪些类型/不输出哪些类型等；每种文档引擎都会有一些额外的配置项，用于特定的配置。

更多的细节请参看文档引擎。

生成代码文档
　选择好文档引擎，并做好相应的配置。您就可以点击“生成”按钮让 NDoc 创建您需要的代码文档了。设计器下方的“输出”窗口中将显示文档制作中的消息，状态条上的进度条指示生成的整体进度。

NDoc 生成进度

查看文档
　生成成功后，您可以点击“查看文档”按钮查看生成的代码文档。

概述
　NDoc 项目文件保存了您要输出代码文档的程序集、相应的 XML 文档、选用的文档引擎及配置参数等信息。

NDoc 项目设计器

新建 NDoc 项目的工作可以很简单：选择要输出代码文档的程序集、相应的 XML 文档、选择一个文档引擎并做好配置参数。

命名空间摘要
　标准的 C# 注释 XML 文档中，没有提供任何标记为命名空间提供“summary”文档。NDoc 提供了两种途径允许您为命名空间提供“summary”文档。一种是通过在您的代码加入特定的类，并对 NDoc 文档引擎作相应配置（请参见 NDoc 文档引擎中关于 UseNamespaceDocSummaries 配置项的说明）。另一种途径是通过项目设计器指定各命名空间的摘要文档。

在项目设计器中，单击“命名空间摘要”按钮，在弹出的“编辑命名空间摘要”对话框中，给每个命名空间填写摘要文档。

这些摘要文档将包含在最终生成的代码文档中。

编辑命名空间摘要对话框

文档引擎配置
各种文档引擎间共享一些基本配置项，比如输出过滤(是否输出 private 成员等)，缺少文档时的处理对策等；各文档引擎又包含自己的某些特殊配置项。这些配置项都可以通过项目设计器查看、更改，并保存到项目文件中。

设计器中配置项以类别排列，并且，选中某一配置项时会显示一小段提示文本，说明该配置项的用途和用法。这些都将帮助您快速掌握这些文档引擎的使用方法。

关于完整的文档引擎列表，及其配置项，请参见 NDoc 文档引擎。

选项

选项	说明
ShowProgressOnBuild	如果为真，在文档生成动作启动时，消息输出窗口将自动显示出来。
LoadLastProjectOnStartup	如果为真，每次启动 NDoc 时将自动加载最后一次打开的项目文件。此配置和登陆的 Windows 用户相关。
MRUSize	“最近的项目”列表中显示的最大条目数。
HtmlHelpWorkshopLocation	HTML Help Workshop 软件安装路径，即 HHC.exe 编译器的所在目录。仅对 MSDN 和 MSDN 2003 文档引擎有效。默认情况下，MSDN 和 MSDN 2003 文档引擎会尝试查找 HTML Help 1 编译器的所在位置，但仍会出现无法定位的情况。这时，NDoc 会提示您无法找到 HHC.exe 编译器，您需要设置此配置项解决问题。此配置为机器级别的配置，在此机器上的任何 Windows 用户都共享此配置。

概述
　NDoc 不仅提供了 GUI 的界面，也同时提供了命令行工具(NDocConsole.exe)，为和其他开发工具集成提供了方便。
　
　语法
　NDoc 命令行使用简单的“name-value 对”语法来指定相应的配置项。每个选项前用一个短线，如：-name=value，短线和等号周围不要有空格。下面语法叙述中，中括号的部分是可选的。路径中如果包含有空格，则需要用引号(")括起来。
　用法 1

NDocConsole 程序集[,XML文档] [程序集[,XML文档]]...
[[-referencepath=文件夹] [-referencepath=文件夹]...]
[-namespacesummaries=文件名]
[-documenter=文档引擎]
[[-引擎参数=值] [-引擎参数=值]...]
[-verbose]

注释:

程序集: 要生成文档的完整路径。
XML文档: 对应的 XML 文档（C# 编译器 /doc 输出的 XML 文档）。
缺省时，将自动查找和程序集相同路径、相同名称，仅扩展名不同(.xml)的 XML 文件代替。
referencepath: 引用的第三方 dll 的搜索路径。
namespacesummaries: 要使用的命名空间摘要 XML 文档的完整路径。
documenter: 要使用的文档引擎的名称。注意此项区分大小写。
缺省时，将使用 MSDN 文档引擎。
引擎参数: 文档引擎的配置参数名称，注意此项区分大小写。
值: 给引擎参数设置的值。
verbose: 显示文档生成进度的输出消息。

用法 2

NDocConsole -recurse=文件夹[,最大读取深度]
[[-referencepath=文件夹] [-referencepath=文件夹]...]
[-namespacesummaries=文件名]
[-documenter=文档引擎]
[[-引擎参数=值] [-引擎参数=值]...]
[-verbose]

注释:

recurse: 您可以将要生成文档的程序集和它们对应的 XML 文档放在同一文件夹中（注意：XML 文档的文件名应和对应的程序集文件名相同，仅扩展名不同），将此文件夹指定给此参数，NDoc 将自动查找程序集和 XML 文档。这是一种比较简单的用法。
最大读取深度: 在 recurse 参数指定的文件夹中的读取深度。
referencepath: 引用的第三方 dll 的搜索路径。
namespacesummaries要使用的命名空间摘要 XML 文档的完整路径。
documenter: 要使用的文档引擎的名称。注意此项区分大小写。
缺省时，将使用 MSDN 文档引擎。
引擎参数: 文档引擎的配置参数名称，注意此项区分大小写。
值: 给引擎参数设置的值。
verbose: 显示文档生成进度的输出消息。

用法 3
　NDocConsole [-documenter=文档引擎] -project=NDOC项目文件 [-verbose]
　
　注释:

documenter: 要使用的文档引擎的名称。注意此项区分大小写。
缺省时，将使用 MSDN 文档引擎。
project: 您可以使用 NDoc GUI 界面保存一个 NDoc 项目文件，然后设置给此参数。
verbose: 显示文档生成进度的输出消息。

用法 4
　NDocConsole [-help] [文档引擎 [引擎参数]]
　
　where:

help: 显示命令行帮助信息。
如果文档引擎参数没有指定，显示 NDoc 命令行的基本语法。
文档引擎: 显示此文档引擎的帮助信息（如：可用的配置参数项等）。注意此项区分大小写。
如果引擎参数没有指定，显示此文档引擎可用的配置参数列表。
引擎参数: 显示文档引擎的某配置参数的信息，如描述、默认值。若参数为枚举类型，还会列出可用的枚举值（使用时注意区分大小写）。

可用的文档引擎
　NDoc 1.3 自带的文档引擎包括: JavaDoc, LaTeX, LinearHtml, MSDN, MSDN_2003, VS.NET_2003, 以及 XML。

您可以使用 NDocConsole -help 看到实际的列表。

命名空间摘要 XML 文档的语法

<namespaces>
<namespace name="My.NameSpace">My summary.</namespace>
<namespace name="My.OtherNameSpace">My other summary.</namespace>
...
</namespaces>

配置 NAnt(暂无)

配置 VS.NET
　您可以利用 VS.NET 中提供的生成事件功能，将 NDoc 配置为在每次代码编译完成后、自动生成相应的代码文档。同时 NDoc 代码文档生成将花费不少时间，因此建议您只在 Release 配置状态(或其他自定义的配置状态)时允许自动文档生成。

而 C# 项目的生成事件并不区分各种配置状态(如 Debug 或 Release )，因此需要在生成事件的脚本中添加对配置状态(VS.NET 内置的编译变量)的判断，如：

if $(ConfigurationName) == Release
　因为直接在生成事件窗口中正确书写 NDoc 命令行命令及相关参数、很困难也很容易出现错误，因此您可以将命令写在一个批处理 .bat 文件中，而在项目的生成后事件中引用这个批处理文件(如下图)，这样比较容易书写和维护。

Calling a batch file from the post-build event

一个解决方案中有多个项目时，如果您要得到一份整合的代码文档，您可以只在编译顺序中最后的那个项目配置中，填写这个生成后事件命令。如果您想为每个项目单独生成一份文档，则需要分别去配置。您可以根据您的实际情况决定。

关于 NDoc.bat 中的写法，您可以参考下面的命名行（它对应于上面图中的生成后事件命令）：

IF NOT %1 == Release GOTO end

"%ProgramFiles%\NDoc 1.3\bin\net\1.1\NDocConsole.exe" -recurse="%2bin\%1"

:end
　复杂的解决方案中，可能需要更加复杂的配置，比如有时配置第三方 dll 的搜索路径等，仔细研究一下 NDocConsole.exe -help 的帮助信息吧！

其他开发工具的配置
　大多数开发工具都有运行命令行程序的选项，这些开发工具都可以使用 NDoc 命令行来实现代码文档的自动生成。每种开发工具的配置方法可能不同，但思路都很类似上面关于 VS.NET 中的想法。

概述
　文档引擎是生成各种格式代码文档的组件。NDoc 1.3 内建了以下文档引擎:

VS.NET
MSDN
MSDN 2003
XML
JavaDoc
LinearHtml
LaTeX
NDoc 的设计具有很强的可扩展性，您可以自己创作输出特定格式文档的、新的文档引擎。

代码文档的制作一般分作两大环节:

将从程序集中通过反射发出读取的类型/成员信息，和 /doc XML 文档中的注释文档，合并在一起，即 NDoc 中间 XML 数据文件。
通过 XSLT 转换将 NDoc 中间 XML 数据文件转换为目标 HTML 格式。
您可以通过 XML 文档引擎得到 NDoc 中间 XML 数据文件，经过分析和转换，创作您自己的文档引擎。

下面配置项，是 NDoc 所有文档引擎中通用的配置项，各文档引擎还可以有自己的一些特殊配置，详见文档引擎的文档。

通用的配置

配置项

说明

(全局)

ReferencePaths

一组额外的程序集搜索路径。
注意：这是一个 NDoc 项目级别的属性，各文档引擎共享此项配置。

文档主要配置

AssemblyVersionInfo

如何输出版本信息。
可选项为:

None	不输出版本信息。(默认选项)
AssemblyVersion	输出标准 .NET 的版本号，即通过 AssemblyVersionAttribute 属性设置的版本号。
AssemblyFileVersion	通过 AssemblyFileVersionAttribute 属性指定的版本号。如果程序集需要安装到 GAC，通过这种方式指定程序集的版本比较常见。

AutoDocumentConstructors

若此项为真，文档引擎将为类型的默认构造函数(即不附带参数的那个构造函数)添加默认的 summary 文档。

AutoPropertyBackerSummaries

若此项为真，文档引擎会把字段 _Length 或 length 视为属性 'Length' 的辅助字段，在 _Length 或 length 缺少文档信息时，自动为它添加 summary 信息(“属性 Length 的辅助字段。”)。

CleanIntermediates

是否在文档成功生成后，删除中间文件。
比如 MSDN 和 VS.NET 文档引擎会编译为单一文件，它们的中间文件包括所有编译前的网页、HTML Help 项目文件等。

CopyrightHref

CopyrightText

FeedbackEmailAddress

用户反馈接收 Email 地址。将在输出的代码文档每页的底部添加放置指向此 Email 地址的超链接。

Preliminary

若此项为真，文档引擎将在每个页面中添加红色的消息“[此文档为预发布版本，在未来版本中有可能改变。]”。

SdkDocLanguge

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪种本地化语言版本的 .NET Framework SDK。

SdkDocVersion

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪个版本的 .NET Framework SDK。

UseNamespaceDocSummaries

若此项为真，文档引擎将在每个命名空间中查找一个名为 NamespaceDoc 的类，并将它的 summary 信息作为这个命名空间的 summary，这个类本身不会出现在最终的代码文档中。
如果需要，您可以使用 #if ... #endif，配合条件编译常数，在最终 Release 程序集中排除 NamespaceDoc 类。

UseNDocXmlFile

主要用于调试用途，一般情况下请留空白。NDoc 会首先生成中间 XML 数据文件（可以使用 XML 文档引擎得到），然后通过 XLST 转换为各种 HTML 格式。如果希望创作自定义的文档引擎，可以将此选项配置为事先生成的一个 NDoc 中间 XML 数据文件，这样将提高您的调试效率。

属性(attribute)的输出

DocumentAttributes

是否输出类型和成员的属性(attribute)。

DocumentedAttributes

属性(attribute)输出的过滤。当 DocumentAttributes = true 时，此配置指示将输出哪些属性，其他属性被过滤掉。
请使用编辑器生成，有效的格式应为：

'<attribute-name-starts-with>,<property-to-show>,<property-to-show>|<attribute-name-starts-with>,<property-to-show>,<property-to-show>|(etc...)'

如果为空白，则输出全部属性。

DocumentInheritedAttributes

是否输出从基类中继承而来的属性(attribute)。如果 DocumentAttributes = false，则此配置被忽略。

ShowTypeIdInAttributes

是否在属性(attribute)输出时输出 TypeId 值。如果 DocumentAttributes = false，则此配置被忽略。

缺少文档时的输出

ShowMissingParams

缺少 <param> 参数文档时，是否输出红色的提示文本。

ShowMissingRemarks

缺少 <remarks> 备注文档时，是否输出红色的提示文本。

ShowMissingReturns

缺少 <returns> 返回值文档时，是否输出红色的提示文本。

ShowMissingSummaries

缺少 <summary> 概述文档时，是否输出红色的提示文本。

ShowMissingValues

缺少 <values> 属性值文档时，是否输出红色的提示文本。

XLinks
　HTML Help 1 直接使用 HTML <A> 标记表示超链接。Microsoft Help 2 引入了新的 XLinks 机制 (是微软对 W3C XLinks 的一个实现)，来表示指向其他文档集合的超链接。一个 XLink 很像 HTML <A> 链接，但包含额外的元数据用于表示复杂的链接。Microsoft Help 2 使用 XLinks 不直接使用路径/文件名，而根据在“索引”表中检索特定的关键字查找。

NDoc 为指向 .NET Framework 类型/成员的链接（包括成员列表中指向基类型的链接、以及使用 <see> 标记加入的指向 .NET Framework 或第三方类库中的类型/成员的显式链接），制作 XLinks 链接。下面是一个指向 System.Void 的示例 XLink:

<MSHelp:link

keywords="frlrfSystemVoidClassTopic"

indexMoniker="!DefaultAssociativeIndex"

namespace="ms-help://MS.NETFrameworkSDKv1.1.CHS">void</MSHelp:link>

上面 XLink 的三个属性指示了查找这个帮助主题的方法。属性 namespace 指示在哪个文档命名空间中查找(每个帮助文档集合都需要在机器中注册一个唯一的命名空间，如上面的 ms-help://MS.NETFrameworkSDKv1.1.CHS 表示 .NET Framework SDK 类库文档的帮助文档集合)。属性 indexMoniker 指示使用哪种类型的“索引”(Microsoft Help 2 索引可以有很多类型，其中，DefaultAssociativeIndex 常用于创建帮助主题之间的关联)。最后，keyword 指示要指向哪个帮助主题页面。

每个页面头部的嵌入 XML 数据岛中都包含若干 Keywords，您可以在 .NET Framework SDK 类库文档中查看 System.Void 页面中，包含如下的一行:

<MSHelp:Keyword Index="A" Term="frlrfSystemVoidMembersTopic"/>

这个 frlrfSystemVoidMembersTopic 就是在 .NET Framework SDK 类库文档中，用 DefaultAssociativeIndex 类型的“索引”中的 keyword。

链接到 .NET Framework SDK 类库文档
　指向到 .NET Framework SDK 类库文档的超链接，不需要您费心，NDoc 已经可以做的很好。您尽管从 .NET Framework 的基类型继承、创作您的子类型，或者使用 <see> 等标记加入这些链接，NDoc 自动处理这些关于 XLinks 的事情。

链接到第三方类库文档
　NDoc 允许您创建指向到第三方类库文档的超链接，不过也需要严格按照上面介绍的 XLinks 体制来做。首先找到该文档集合的命名空间，和要指向的帮助主题 HTML 页头部中的 keyword，做好准备。(如果那个文档集合也是用 NDoc 1.3 生成的，则页面头部的 XML 数据岛已经按要求写好了 keyword。)

因为 NDoc 只能找到子类型的父类型的名称，<see> 标记中最终 NDoc 看到的也只是要指向的类型/成员的完全名称；NDoc 不知道这些类型/成员的文档存在哪个文档集合中。您需要告诉 NDoc：哪些类型/成员的帮助文档在哪个文档命名空间，而另一些类型/成员在另一个文档命名空间，也就是各 .NET 类型/成员和 Microsoft Help 2 帮助文档命名空间之间的映射关系。这就需要您指定 NamespaceMappingFile 了（请参见 VS.NET 2003 文档引擎的 UseHelpNamespaceMappingFile 配置项）。NamespaceMappingFile 是一个 XML 文件，它必须符合 NamespaceMapping XSD 架构(请右击“另存为...”)。

</helpNamespace>

</helpNamespace>

</namespaceMap>

NamespaceMappingFile 的一个实例:

<?xml version="1.0" encoding="utf-8"?>
<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">
<helpNamespace ns="ms-help://MS.NETFrameworkSDKv1.1.CHS">
<managedNamespace ns="System" />
<managedNamespace ns="Microsoft" />
</helpNamespace>
</namespaceMap>

　上面的例子表示指向 System 和 Microsoft 命名空间的类型/成员的链接，将被指向 ms-help://MS.NETFrameworkSDKv1.1.CHS 帮助文档命名空间。

指定了 NamespaceMappingFile 之后，其他的工作都可以交给 NDoc 来做了。

与 Visual Studio .NET IDE 的集成

　.NET Framework SDK 类库文档的每一个页面的头部都有一个嵌入的 XML 数据岛。在 Microsoft 文档资源管理器中，这些 XML 数据岛用于创建索引，链接帮助主题，查找关键字，筛选帮助主题，以及很多其他功能。Visual Studio .NET IDE 中的“动态帮助”功能也依赖于这些嵌入的 XML 数据。以下是一个 XML 数据岛示例：

<xml>

<MSHelp:TOCTitle Title="Object Class"/>

<MSHelp:RLTitle Title="Object Class"/>

<MSHelp:Keyword Index="K" Term="Object class, about Object class"/>

<MSHelp:Keyword Index="A" Term="frlrfSystemObjectClassTopic"/>

<MSHelp:Keyword Index="F" Term="System.Object"/>

<MSHelp:Attr Name="DocSet" Value="NETFramework"/>

<MSHelp:Attr Name="TopicType" Value="kbSyntax"/>

<MSHelp:Attr Name="DevLang" Value="CSharp"/>

<MSHelp:Attr Name="DevLang" Value="VB"/>

<MSHelp:Attr Name="DevLang" Value="C++"/>

<MSHelp:Attr Name="DevLang" Value="JScript"/>

<MSHelp:Attr Name="DevLang" Value="VJ#"/>

<MSHelp:Attr Name="Technology" Value="WFC"/>

<MSHelp:Attr Name="Technology" Value="ManagedC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbWFC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbManagedC"/>

<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

<MSHelp:Attr Name="DocSet" Value="NETCompactFramework"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbProfile2NETCF"/>

<MSHelp:Attr Name="HelpPriority" Value="2"/>

</xml>

NDoc VS.NET 文档引擎同样创建这样的 XML 数据岛，以提高和 Microsoft 文档资源管理器以及 VS.NET IDE 的集成性。

要求

　尽管 NDoc 为每一帮助主题生成必要的 XML 数据岛，但要更好的利用 Microsoft Help 2 的功能（如筛选器等），还需要了解更多的背景知识。

Help Title 必须存在于一个帮助集合中。

Microsoft Help 2 定义了两个级别的帮助文档容器：Help Title 和帮助集合。Help Title 是一组相关的帮助主题，编译为一个 .HxS 文件。帮助集合是一个或多个 Help Title 的集合。(您可以这样理解：一个 Help Title 可以被当作一个帮助集合，但反过来不成立。) 每个帮助集合必须分配有一个唯一的命名空间。

只有帮助集合才能被集成到 VS.NET 的帮助系统中。

帮助集合必须在每台机器上注册后才能被访问。

Microsoft Help 2 帮助系统维护一个注册表(不要和 Windows 注册表混淆)，保存当前机器中所有已安装的帮助集合。此注册表用于定位超链接的目的地，执行检索，显示索引等。这是 Microsoft Help 2 中一个核心的部分。

因为这个原因，帮助集合必须在安装时注册到每台客户端机器中，否则将无法访问得到。

已注册的帮助集合可以被“plugged-in”进 VS.NET 合并文档集合。

Microsoft Help 2 允许帮助集合的插接。可以将您的帮助集合插接到其他已有的帮助集合中，比如 VS.NET 合并文档集合，它的命名空间是 MS.VSCC.2003。

还很糊涂？

　Microsoft Help 2 确实是一套复杂的技术。更深入的信息请查阅 VSHIK 文档。网站 helpware.net 提供了很多有关 Microsoft Help 2 的有用资料和教程。HelpWare 还提供了一个名为 FAR 的共享软件，它更证明了 Microsoft Help 2 帮助系统的潜力。

VS.NET 文档引擎使用了几个配置项，意在简化整个过程。

首先，您应该设置 GenerateCollectionFiles 为 true。这将指示 NDoc 将生成的文档合并到 VS.NET 合并文档集合中去。

然后，您需要指定 CollectionNamespace，帮助集合的命名空间名称。不要使用空格、汉字等 URI 中不允许的字符。建议您设法让这个命名空间名称不容易重复，比如以您的公司名开始，等等。

第三步，指定 PlugInNamespace。它表示要“plugged-in”到哪个文档集合中去。当使用 h2reg.exe 部署您的帮助文档时，它们被插接到 VS.NET 的合并文档集合中去。默认值 ms.vscc 指示 h2reg.exe 自动判断 VS.NET 是 2002 或 2003 版本。

筛选器

　每个帮助主题的 XML 数据岛中可以包含一个或多个 DocSet 值。在文档资源管理器及 VS.NET IDE 中，这些 DocSet 值常常被各个筛选器用于筛选帮助索引及搜索范围。

默认的一些筛选器定义如下:

Windows Client SDK, 　　Query: "DocSet"="WCSDK"
.NET Framework, 　　　　Query: ("DocSet"="NETFramework" OR "DocSet" = "NETFrameworkExtender") OR (("DocSet"="C#" OR "DocSet"="Visual Basic" OR "DocSet"="Visual C++" OR "DocSet"="VBA" OR "DocSet"="VJ#" OR "DocSet"="Visual Studio") AND "Technology"="ManagedCode")
Visual Studio 宏, 　　　Query: "DocSet" = "VSM" OR "DocSet" = "NETFramework"
Visual Basic, 　　　　　Query: "DocSet" = "Visual Basic" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVBp700")
Visual C++, 　　　　　　Query: "DevLang" = "C" OR "DevLang" = "C++" OR "Product" = "VC" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVC700")
Platform SDK, 　　　　　Query: "DocSet" = "PSDK"
(no filter), 　　　　　Query:
企业级服务器, 　　　　Query: "DocSet" = "NETEnterpriseServers" OR "DocSet" = "SQL Server"
Internet 开发,　　　　Query: "DocSet" = "DHTML" OR "DocSet" = "XML" OR "DevLang" = "DHTML" OR "DevLang" = "HTML" OR "DevLang" = "VBScript" OR "DevLang" = "JScript" OR "DevLang" = "ASP" OR "Technology" = "kbSOAP" OR "Technology" = "ASPNET" OR "Technology" = "HPS"
Visual Studio, 　　　Query: "DocSet" = "Visual Studio" OR "DocSet" = "Visual Studio SDK" OR "DocSet" = "CrystalReports" OR "DocSet" = "Visual Source Safe" OR "DocSet" = "VSAnalyzer" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "NETEnterpriseServers" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVS700")
Visual C#, 　　　　　Query: "DocSet" = "C#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "C#")
Samples, Query: "TopicType"="kbSampleProd"
Visual FoxPro, 　　　Query: "DocSet" = "Visual FoxPro" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVFP700")
Knowledge Base, 　　Query: "DocSet" = "kbKB"
Visual J#,　　　　　Query: "DocSet" = "VJ#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "VJ#")
.NET Framework 精简版, Query: "DocSet"="Smart Devices" OR "DocSet"="NetCompactFramework"
中文(简体)文档,　　　 Query: ("Locale"="kbChineseSimp")

将您的帮助集合加入上面这些筛选器的搜索范围，可以很简单的指定文档引擎的 DocSetList 配置项。它是一个逗号分隔的字符串，每一项最终都被写成 XML 数据岛中的一行 DocSet 值。当用户使用这些筛选器时，如果您的帮助页面 XML 数据岛中具有特定的 DocSet 值，您的帮助文档就会被包括在搜索范围中。

NDoc 默认将 HtmlHelpName 作为一行 DocSet 值写入每页的 XML 数据岛。您不需要通过 DocSetList 重复定义它。

NDoc 默认会注册一个新的筛选器，这个筛选器的查询条件是 "DocSet" = "HtmlHelpName"，即这个筛选器将只搜索这个帮助集合的内容。Microsoft Help 2 允许您定义其他自定义的筛选器，但已经超出 NDoc 的工作范围，您需要自行查阅 VSHIK 文档，修改 Microsoft Help 2 项目文件重新编译。

部署 Microsoft Help 2

　Microsoft Help 2 帮助系统维护一个注册表(不要和 Windows 注册表混淆)，保存当前机器中所有已安装的帮助集合。注册表保存了所有的帮助集合，每个帮助集合中包含的 Help Titles，帮助集合间的嵌套关系等。

查看 Microsoft Help 2 Title 或集合之前，必须首先注册。因此 Microsoft Help 2 文档的部署，要比 HTML Help 1 的简单文件拷贝复杂的多。

Windows Installer
　可以通过创建一个 Windows Installer 安装包程序，用于部署并注册帮助集合和 Help Titles。VSHIK 文档中有具体的制作步骤。不幸的是，这个过程中有很多手工的步骤，我们还没有能够找到自动制作 Windows Installer 安装包的方法。

H2Reg
　另一格选择是使用 helpware.net 提供的共享软件 H2Reg.exe。H2Reg.exe 是一个命名行工具，可以在安装过程中使用它，完成帮助集合/Help Title 的注册。它可以被用于任何支持命令行的安装程序，比如对于 Windows Installer 安装包，H2Reg 可以作为一个自定义动作。

如果设置 GenerateCollectionFiles 为 true，NDoc 会为 H2Reg 创建特定的 INI 配置文件，H2Reg 可以根据这个 INI 配置文件完成 Help Title 的注册、并合并到 VS.NET 的合并文档集合等动作。(记得将这个 INI 配置文件包含进您的安装包。)

下面是完整的步骤:

设置文档引擎的 GenerateCollectionFiles 为 true
将编译生成的帮助文件(*.HxS, *.HxI 等)，和生成的 INI 文件包含到安装包中。
将 H2Reg.exe 和 H2Reg.ini (此文件可以从 H2Reg 安装路径中拷贝出来)包含到安装包中。
配置安装包，让安装包安装时，将帮助文件和生成的 INI 文件复制到安装路径下。
安装动作：执行 H2Reg，语法为:
H2reg -r "CmdFile=<生成的 INI 文件的完整路径>"
卸载动作：执行 H2Reg，语法为:
H2reg -u "CmdFile=<生成的 INI 文件的完整路径>"

注意: 先执行 H2Reg，再删除相应的帮助文件和 INI 文件。

概述
　MSDN 文档引擎用于生成如 .NET Framework SDK 类库文档样式的代码文档，并编译为 HTML Help 1 格式的单一文件(*.CHM)。

MSDN 2003 文档引擎是 NDoc 1.3 对 MSDN 文档引擎的改进，加入了语言选择器等功能，更加接近 .NET Framework SDK 文档的样式。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
AdditionalContentResourceDirectory	页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
BinaryTOC	是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。
ExtensibilityStylesheet	用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
FilesToInclude	指定需要包含在 HTML Help 项目中的附加文件。(1)允许使用绝对路径或相对路径指定，相对路径相对于 NDoc 项目文件所在目录。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多个地址，用符号 "\|" 隔开。
FooterHtml	自定义的 HTML 页脚。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 被替换为该页面的标题文字，"%ASSEMBLY_NAME%" 和 "%ASSEMBLY_VERSION%" 分别被替换为当前页面对应类型所属程序集的名称和版本信息。
HeaderHtml	自定义的 HTML 页头。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 则被替换为该页面的标题文字。
HtmlHelpName	一个名称，用于命名生成的 HTML Help 项目以及将要生成的 CHM 文件。
IncludeFavorites	是否在生成的 HTML Help 文件中包含“收藏”选项卡。
LangID HTML Help	文件的 LangID 设置。中文版默认为 2052。
OutputDirectory	输出文件目录，生成的 .html 和 .chm 文件都将存放于此目录。
OutputTarget	输出目标格式: HTML Help (.chm) 或 Web 网页或两者都输出。
RootPageContainsNamespaces	如果为真，RootPageFileName指定的主页面，将在目录树中表示为所有命名空间结点的容器（父结点）。否则，将和其他命名空间结点并列表示。
RootPageFileName	通过此项指定 HTML Help 文件中的主页面文件名。注：此处主页指打开 CHM 文件时显示的第一个页面，请通过 RootPageTOCName 指定此主页面在目录树中的显示名称；通过 RootPageContainsNamespaces 指定此主页面在目录树中的显示样式；可以通过 FilesToInclude 将此文件引入到此 HTML Help 项目中来。
RootPageTOCName	HTML Help 文件中，主页在目录树中的显示名称。若 RootPageFileName 指定了某一页面，而此项没有指定，则将在目录树中显示“概述”作为名称。注：此处主页指打开 CHM 文件时显示的第一个页面。
SdkLinksOnWeb	如果为真，类库中所有指向 .NET Framework 标准类库的文档超链接都将指向 MSDN 的在线版本。否则，将指向本地版本。
ShowVisualBasic	是否为类型和成员显示 Visual Basic 语法块。
Title	此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。

将附加的文件加入要编译的 CHM 文件中

　MSDN 文档引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 两种途径，允许您附加额外的文件。

前者允许您使用 * 或 ? 通配符的形式指定要包含的文件路径，可以指定多个路径，用“|”隔开。如果使用相对路径，应相对于 NDoc 项目文件所在的目录。注意：在最终编译的 CHM 中，这些被附加的文件，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中。

后者将一个文件夹中的内容(包括子文件夹中的全部内容)全部读入。注意：在最终编译的 CHM 中，AdditionalContentResourceDirectory 文件夹第一级的文件和文件夹，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中；该目录的子目录及其中内容，将保持原有父子关系。例如 AdditionalContentResourceDirectory 是 D:\temp ，这个目录中有 my.css 文件和 images 子目录，images 目录中有 logo.gif 文件，则 my.css 和其他 NDoc 生成的文件同级，使用相对路径引用 my.css 时为“my.css”；而引用 logo.gif 应为“images/logo.gif”。

请根据您的具体情况进行选择具体采用哪种方式。

另外，RootPageFileName 指定 CHM 打开时的第一个页面文件，这个页面可以是 NDoc 生成的文件，也可以是通过上述两种方式附加进去的某 HTML 文件。

概述
　MSDN 2003 文档引擎是 NDoc 1.3 对 MSDN 文档引擎的改进，加入了语言选择器等功能，更加接近 .NET Framework SDK 文档的样式。它用于生成如 .NET Framework SDK 类库文档样式的代码文档，并编译为 HTML Help 1 格式的单一文件(*.CHM)。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
AdditionalContentResourceDirectory	页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
BinaryTOC	是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。
ExtensibilityStylesheet	用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
FilesToInclude	指定需要包含在 HTML Help 项目中的附加文件。(1)允许使用绝对路径或相对路径指定，相对路径相对于 NDoc 项目文件所在目录。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多个地址，用符号 "\|" 隔开。
FooterHtml	自定义的 HTML 页脚。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 被替换为该页面的标题文字，"%ASSEMBLY_NAME%" 和 "%ASSEMBLY_VERSION%" 分别被替换为当前页面对应类型所属程序集的名称和版本信息。
HeaderHtml	自定义的 HTML 页头。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 则被替换为该页面的标题文字。
HtmlHelpName	一个名称，用于命名生成的 HTML Help 项目以及将要生成的 CHM 文件。
IncludeFavorites	是否在生成的 HTML Help 文件中包含“收藏”选项卡。 LangID HTML Help 文件的 LangID 设置。中文版默认为 2052。
OutputDirectory	输出文件目录，生成的 .html 和 .chm 文件都将存放于此目录。
OutputTarget	输出目标格式: HTML Help (.chm) 或 Web 网页或两者都输出。
RootPageContainsNamespaces	如果为真，RootPageFileName 指定的主页面，将在目录树中表示为所有命名空间结点的容器（父结点）。否则，将和其他命名空间结点并列表示。
RootPageFileName	通过此项指定 HTML Help 文件中的主页面文件名。注：此处主页指打开 CHM 文件时显示的第一个页面，请通过 RootPageTOCName 指定此主页面在目录树中的显示名称；
RootPageContainsNamespaces	指定此主页面在目录树中的显示样式；可以通过 FilesToInclude 将此文件引入到此 HTML Help 项目中来。
RootPageTOCName	HTML Help 文件中，主页在目录树中的显示名称。若
RootPageFileName	指定了某一页面，而此项没有指定，则将在目录树中显示“概述”作为名称。注：此处主页指打开 CHM 文件时显示的第一个页面。
SdkLinksOnWeb	如果为真，类库中所有指向 .NET Framework 标准类库的文档超链接都将指向 MSDN 的在线版本。否则，将指向本地版本。
Title	此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。

将附加的文件加入要编译的 CHM 文件中
　MSDN 文档引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 两种途径，允许您附加额外的文件。

请根据您的具体情况进行选择具体采用哪种方式。

另外，RootPageFileName 指定 CHM 打开时的第一个页面文件，这个页面可以是 NDoc 生成的文件，也可以是通过上述两种方式附加进去的某 HTML 文件。
　
　概述
　XML 文档引擎是 NDoc 中最简单的文档引擎，它直接输出 NDoc 生成的中间 XML 文件。主要帮助开发人员调试 NDoc 扩展 XSLT 转换，以及制作新的自定义文档引擎。

请参见 NDoc 可扩展性和实现一个新的文档引擎。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
OutputFile	输出 XML 文件名。XML 文档引擎输出 NDoc 文档生成器所使用的中间 XML 格式数据，适用于自定义文档引擎的制作与调试。

概述
　JavaDoc 文档引擎用于创建类似 JavaDoc (Java 社区中，自动创建代码文档的工具) 布局和格式的 HTML 代码文档。

因为缺少足够的关注度，此文档引擎的开发并不活跃。如果您有兴趣进一步完善此文档引擎，请联络 NDoc 项目管理员。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
Title JavaDoc	项目标题。
OutputDirectory	存放输出 HTML 文件的文件夹。可以为绝对路径或者相对于 NDoc 项目文件的相对路径。

概述
　Linear HTML 文档引擎用于生成单一 HTML 文件的代码文档。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
OutputDirectory	目标 HTML 文件的输出目录。
Title	HTML 页的标题。
IncludeTypeMemberDetails	是否输出类型成员的细节（如：是否显示字段、属性的“备注”等，是否单独显示方法的参数表格）
MethodParametersInTable	是否在同一表格中显示方法的参数列表。
TypeIncludeRegexp	一个正则表达式，设置此项可以过滤类型的输出，只有符合正则表达式的类型被输出。留空白则输出全部。
amespaceExcludeRegexp	一个正则表达式，设置此项可以过滤命名空间的输出，符合正则表达式的命名空间被过滤。留空白则关闭过滤。

概述
　LaTeX 文档引擎用于创建 dvi、pdf、postscript 等 LaTeX 格式的代码文档。

您需要安装一个 LaTeX 编译器，比如免费的 MiKTeX。关于 LaTeX 的中文支持问题，请参见 CTeX: 中文 TeX 网站中的相关内容。

配置
　所有文档引擎都具有一些通用的配置项。

配置项	说明
OutputDirectory	文件输出目录。
LatexCompiler LaTeX	编译器路径。(如果您没有安装 LaTeX 编译器，请保持空白。)
TexFileBaseName	目标 LaTeX 文件名，请不要加扩展名。

NDoc 内置的 MSDN, MSDN 2003, VS.NET 文档引擎，支持 C# 程序员参考中的所有 XML 文档注释标记。

NDoc 支持扩充的标记和语法。某些标记只能用于特定的类型（类，结构，委托，接口，枚举）或成员（字段，属性，方法，事件等），请参见标记用法。

NDoc 将标记区分为三类: Section 标记，Block 标记，Inline 标记。

标记	说明
<event>[NDoc 扩充]	对某个成员可能引发的事件的说明。
<example>	“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。
<exception>	对某个成员可以抛出的异常的说明。
<exclude/>[NDoc 扩充]	指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。与文档引擎的“可见性”配置不符的，以 exclude 优先。
<include>	将代码文件外部的某 XML 文件中的一部分包含进代码文件来。
<overloads> [NDoc 扩充]	为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。 <overloads> 标记有两种形式: 简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。示例: ///<overloads>This method has two overloads.</overloads> ///<summary>This overload just says hello.</summary> public void SayHello() { ... } ///<summary>This one says hello to someone.</summary> public void SayHello(string toSomeone) { ... }
<param>	成员的参数说明。
<permission>	访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。
<preliminary> [NDoc 扩充]	将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 <para> 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。
<remarks>	“备注”，对 <summary> 的进一步注解。
<returns>	“返回值”。
<seealso>	向页面的“请参见”区域添加一个链接。请不要将此标记包含在 <remarks> 内部，它是一个顶级标记。两种可选的语法: <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso> <seealso cref="System.Data.DataSet">DataSet</seealso>
<summary>	“摘要”，对类型/成员的摘要说明。
<threadsafety>[NDoc 扩充]	“线程安全”，说明类型在多线程环境中是否安全。 NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。 threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如: /// <summary>The summary description for SafeClass.</summary> /// <threadsafety static="true" instance="true"> /// <para>More information about using this class across thread</para> /// </threadsafety> public class SafeClass() { ... }
<value>	“属性值”。

Block 标记
　Block 标记用于 Section 标记的内部，它们将显示在单独的行中。

标记	说明
<code>	多行的代码块。
<list>	一个列表或表格。
<note>[NDoc 扩充]	“注意”块。例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary.
<para>	表示一个段落。

Inline 标记
　Inline 标记可以用于其他 Section 标记或 Block 标记内部，它们将和前后的文本显示在同一行中。

标记	说明
<c>	将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。
<paramref>	加入指向方法参数的链接。
<see>	加入指向某个类型/成员或网络 URL 的链接。两种可选的语法: <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see> <see cref="System.Data.DataSet">DataSet</see> <see langword="xxx"/> 其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

下面的表格显示了各 block 标记的有效性。

　<c> 标记指示将其内部的文本表示为代码样式，Inline 标记，用于表示行文中的代码片断。

<c>text</c>
　其中:

text
　要标记为代码样式的文本。
　应用于
　可用于其他标记内部。

备注
　如果需要标记多行的代码块，请使用 <code> 标记。

示例
　[C#]
　public class MyClass
　{
　/// <summary>
　/// <c>MyMethod</c> is a method in the <c>MyClass</c> class.
　/// </summary>
　public static void MyMethod(int Int1)
　{
　}
　}

　 <code> 标记指示将其内部的文本表示为代码样式，Block 标记，用于表示多行的代码块。

<code [lang="language"][escaped="true"]>content</code>
　其中:

lang="language" [NDoc 扩充]
　语言选择器，表示此代码块仅适用于某种编程语言。(可选)
　escaped="true" [NDoc 扩充]
　若 content 中含有 XML 子级，将它们视为代码的一部分。注意：content 仍然需要是格式完好的 XML。(可选)
　content
　将被表示为代码块的文本。
　应用于
　可用于其他 Section 标记或 Block 标记内部。

备注
　使用 lang 属性表示语言选择器，标准的语言有: Visual Basic, C#, C++ 及 JScript。若代码块适用于多种语言，则用逗号隔开，比如“Visual Basic, C#, C++”。

escaped 为 true 时，其内部所有其他标记都被转义为代码块的一部分。

注意 content 内容必须是格式完好的 XML 注释。否则整个注释块可能被忽略或出错!!!

示例
　下面示例中，因为 escaped="true"，因此直接写入了要作为代码块的 XML 内容。 Note how, in the following comments, the xml text can entered verbatim because the escaped="true" attribute has been applied.

[C#]
　/// <summary>
　/// Loads the XML.
　/// </summary>
　/// <example> The XML should have the following format.
　/// <code escaped="true">
　/// <root>
　/// <member name="name"/>
　/// </root>
　/// </code>
　/// </example>
　public void LoadXml(string xml)
　{
　//do something here...
　}

<event> 标记用于说明被标记的方法可能引发的事件。Section 标记。

<event cref="member">description</event>
　其中:

cref = "member"
　表示可能引发的事件。书写时，如果可能引发的事件是同一类型的事件，member 可以直接写事件名称（注意大小写）；如果是其他类型的，建议您写该事件的完全限定名称。C# 编译器将检查该事件是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
　description
　附加的说明，比如在什么情况下引发该事件。
　应用于
　方法成员。

备注

示例

　 <example> 标记表示“示例”区域。Section 标记。用于书写能辅助使用者理解并快速上手的示例代码等内容。

<example>description</example>
其中:

description
示例及其说明。
应用于
所有的类型及成员。

备注
此标记经常和 <code> 标记联用。

示例
[C#]
public class MyClass
{
/// <summary>
/// The GetZero method.
/// </summary>
/// <example> This sample shows how to call the GetZero method.
/// <code>
/// class MyClass
/// {
/// public static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
public static int GetZero()
{
return 0;
}
}

<exception> 标记用于说明一个成员可能抛出的异常。

<exception cref="member">description</exception>
其中:

cref = "member"
表示可能抛出的异常类型。书写时，如果可能抛出的异常是同一命名空间下的异常类型，member 可以直接写异常名称（注意大小写）；如果是其他命名空间的，建议您写该异常类型的完全限定名称。C# 编译器将检查该异常是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
description
说明信息，比如在什么情况下抛出该异常。
应用于
属性, 方法, 事件, 运算符, 类型转换

备注

示例
[C#]
using System;

/// comment for class
public class EClass : Exception
{
// class definition ...
}

class TestClass
{
/// <exception cref="EClass">Thrown when... .</exception>
public static void Main()
{
...
throw new EClass();
...
}
}

<exclude/> 标记指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。

<exclude/>
应用于
所有的类型及成员。

备注
与文档引擎的“可见性”配置不符的，以 exclude 优先。

示例
请参见

<include> 标记指示将代码文件(*.cs)外部的某 XML 文件中的一部分、作为 XML 文档注释、包含进代码文件来。

<include file='filename' path='tagpath[@name="id"]' />
其中:

filename
包含 XML 文档注释的文件名。该文件名可包含路径。将 filename 括在单引号中 (' ')。
tagpath
filename 中指向标记名的标记路径（使用 XPath 语法）。将此路径括在单引号中 (' ')。
name
注释前边的标记中的名称说明符；名称具有一个 id。
id
位于注释之前的标记的 ID。将此 ID 括在双引号中 (" ")。
应用于
所有的类型及成员。

备注
这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。

<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法，请参见 XPath 文档。

示例
以下是一个多文件示例。第一个文件使用 <include>，如下所列：

[C#]
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
public static void Main()
{
}
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{
}
}
第二个文件 xml_include_tag.doc 包含下列文档注释：

<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>

<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>

</MyDocs>
编译器输出的 XML 文档
<?xml version="1.0"?>
<doc>
<assembly>
<name>t2</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
The summary for this other type.
</summary>
</member>
</members>
</doc>

　 <list> 标记表示一个列表(数字列表或符号列表)，或一个表格，或一个定义表。Block 标记。

<list type="bullet" | "number" | "table" | "definition">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
其中:

term
要定义的项，该项将在 description 中说明/定义。
description
对 term 的说明/定义。
备注
<list> 可以表示为四种样式：bullet 为符号列表，即对应于 HTML 中的 UL 列表；number 为数字列表，即对应于 HTML 中的 OL 列表；table 为表格，将以表格形式表示；definition 为定义列表，显示效果就像本页上方“其中”二字下面对 term 和 description 的定义那样。

<listheader> 对 table 和 definition 有效。对 table，需要为 term 和 description 两列分别指定列标题。对 definition，需要指定标题文本，如本页上方的“其中:”那一行。

<item> 块表示列表中的一项。item 包含子元素 term 和 description。对 bullet 和 number 列表，term 无效也不需要写。对 table 表，可以没有 term，只写 description。对 definition 表，term 和 description 都应该有。

列表可以根据需要包含多个 <item> 块。

示例

　 <note> 标记表示一个“注意”块。

<note type="caution" | "inheritinfo" | "implementnotes">
description
</note>

其中:

description
注意事项。
应用于
可用于其他标记内部。

备注
caution 将显示为“警告”，inheritinfo 将显示为“对继承者的说明”，implementnotes 将显示为“对实施者的说明”。

示例

　 <overloads> 标记为“重载列表”页面提供文档。

简单语法
<overloads>
summary_description
</overloads>

复合语法
<overloads>
<summary>summary_description</summary>
[<remarks>remarks_description</remarks>]
[<example>examples_description</example>]
</overloads>

应用于
属性, 方法, 事件, 运算符。

备注
只需在重载成员的第一个成员前面书写此区域即可。

此标记有两种形式:

简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。
复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。
示例

///<overloads>This method has two overloads.</overloads>
///<summary>This overload just says hello.</summary>
public void SayHello() { ... }
///<summary>This one says hello to someone.</summary>
public void SayHello(string toSomeone) { ... }

<para> 标记表示一个段落。

<para [lang="language"]>content</para>
where:

lang="language" [NDoc 扩充]
表示语言选择器，指示此段落仅对某种编程语言有效。(可选)
content
段落文本。
应用于
可用于其他标记内部。

备注
此标记经常用于 <summary>, <remarks>, 及 <returns> 等标记内部。

使用 lang 属性表示语言选择器，标准的语言有: Visual Basic, C#, C++ 及 JScript。若代码块适用于多种语言，则用逗号隔开，比如“Visual Basic, C#, C++”。

示例
请参见 <summary> 的示例。

The <param> tag describes one of the parameters for the method.

<param name='name'>description</param>
where:

name
The name of a method parameter. Enclose the name in single quotation marks (' ').
description
A description for the parameter.
Applies To
Property, Method, Event, Operator.

Remarks
Example
[C#]
/// text for class MyClass
public class MyClass
{
/// <param name="Int1">Used to indicate status.</param>
public static void MyMethod(int Int1)
{
}
/// text for Main
public static void Main ()
{
}
}
See Also

　 <paramref> 标记引用一个参数，将以代码样式表示该参数名称。

<paramref name="name"/>
其中:

name
参数的名称。
应用于
可用于其他标记内部。

备注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <remarks>MyMethod is a method in the MyClass class.
/// The <paramref name="Int1"/> parameter takes a number.
/// </remarks>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <permission> 标记说明访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。

<permission cref="member">description</permission>
其中:

cref = "member"
表示需要的 CodeAccessPermission 类型。书写时，如果 CodeAccessPermission 是同一命名空间下的类型，member 可以直接写其名称（注意大小写）；如果是其他命名空间的，建议您写该 CodeAccessPermission 的完全限定名称。C# 编译器将检查该 CodeAccessPermission 是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
description
其他说明。
应用于
所有成员。

备注
System.Security.PermissionSet 使您得以指定对成员的访问。

示例
[C#]
using System;
class TestClass
{
/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
public static void Test()
{
}
public static void Main()
{
}
}
　
　 <preliminary> 标记将类型/成员标记为“预发布”。

<preliminary>[description]</preliminary>
其中:

description
对“预发布”的说明文本。(可选)
应用于
所有的类型及成员。

备注
若没有指定 description，则以红色显示默认的文本: “[此文档为预发布版本，在未来版本中有可能改变。]”

如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。

示例
[C#]
// The class summary will get the default message
/// <preliminary/>
public class MyClass
{
/// <preliminary>
/// <para>This method is just for testing right now. It might be removed in the near future</para>
/// </preliminary>
public void Dump ()
{
}
}

　 <remarks> 标记表示对类型或成员的“备注”。

<remarks>description</remarks>
其中:

description
对类型/成员的“备注”。
应用于
所有的类型及成员。

备注
<remarks> 标记用于对 <summary> 摘要信息的补充。.

示例
[C#]
/// <summary>
/// You may have some primary information about this class.
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
public class MyClass
{
/// text for Main
public static void Main ()
{
}
}

　 <returns> 标记用于说明方法的返回值。

<returns>description</returns>
其中:

description
对方法的返回值的说明。
应用于
方法。

备注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <returns>Returns zero.</returns>
public static int GetZero()
{
return 0;
}

/// text for Main
public static void Main ()
{
}
}

　 <see> 标记用于在行文中添加一个超链接。

label
超链接的显示文本。
cref = "member"
表示要链接到的类型(成员)。书写时，如果要链接到的类型(成员)是同一命名空间(类型)中的类型(成员)，member 可以直接写它的名称（注意大小写）；如果是其他命名空间(类型)的，建议您写该类型(成员)的完全限定名称。C# 编译器将检查该类型(成员)是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
href = "URL" [NDoc 扩充]
一个网络 URL 地址。
langword [NDoc 扩充]
将会被当作 .NET 关键字粗体显示。如果 langword 是下面备注中的表格里的某个关键字，还将会被替换为相应的说明文本。
应用于
可用于其他标记内部。

备注
　使用 <seealso> 标记将超链接加入到页面的“请参见”区域。

注意: 在 NDoc 1.3 中，对于 MSDN 和 VS.NET 文档引擎，如果一个区域出现了多个指向同一个类型/成员的文档的 <see>，则只转换第一个为超链接，其余的不表示为超链接、只显示为粗体。这将使页面不至于太杂乱。

可识别的 langword
　如果 langword 为下表中的关键字之一，则会显示右侧相应的说明文本。

langword	显示
null	空引用(Visual Basic 中为 Nothing)
sealed	密封的(Visual Basic 中为 NotInheritable)
static	静态(Visual Basic 中为 Shared)
abstract	抽象(Visual Basic 中为 MustInherit)
virtual	虚拟(Visual Basic 中为 CanOverride)

示例
　请参见 <summary> 中的示例。

<seealso> 标记用于在页面的“请参见”区域添加一个超链接。

<seealso cref="member">[label]</seealso>
或
<seealso href="URL">[label]</seealso>
其中:

备注
使用 <see> 标记在行文中添加超链接。

请不要将此标记包含在 <remarks> 标记内部。

示例
请参见 <summary> 中的示例。

<summary> 标记用于对类型或成员的摘要说明。

<summary>description</summary>
其中:

description
对类型或成员的摘要说明。
应用于
所有的类型及成员。

备注
此标记是所有类型及成员最基本的说明，一般的，应为每个公共的、可见的类型/成员书写 summary 文档。在 Visual Studio .NET IDE 的智能感知功能及对象查看器，还有其他大多数开发工具，都会显示 summary 信息。

<remarks> 标记用于更详细的说明。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyMethod is a method in the MyClass class.
/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine"/> for information about output statements.</para>
/// <seealso cref="MyClass.Main"/>
/// </summary>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <threadsafety> 标记用于说明类型在多线程环境中是否安全。
<threadsafety static="true|false" instance="true|false"/>
其中:

static="true|false"
指示类型的静态成员在多线程环境中是否是安全的。
instance="true|false"
指示类型的实例成员在多线程环境中是否是安全的。
应用于
类, 结构。

备注
示例
[C#]
/// <threadsafety static="true" instance="false"/>
public class MyClass
{
/// not safe across threads
public void InstanceMethod()
{
}

/// safe across threads
public static void StaticMethod()
{
}
}

<value> 标记用于说明属性的值。

<value>property-description</value>
其中:

property-description
对属性值的说明。
应用于
属性。

备注
按照约定，总是应该为属性书写 <value> 标记。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyProperty is a property in the MyClass class.</summary>
/// <value>A string containing the text "MyProperty String".</value>
public string MyProperty()
{
get
{
return "MyProperty String";
}
}

}

NDoc 可扩展性
MSDN, MSDN 2003 和 VS.NET 文档引擎都支持一个可扩展的模型，允许您定义自己专有的标记，并指定它们在代码文档中呈现的样式。您或许已经知道，这些文档引擎都使用 XSLT 转换，将 NDoc 中间 XML 数据文件转换为目标 HTML 格式。NDoc 标记的可扩展性也依赖于此，您可以通过自定义的 XSLT 转换文件加入您自定义的标记。（建议，您需要事先了解一些 XSLT 转换的知识，并分析 XML 文档引擎生成的 NDoc 中间 XML 数据文件中的 XML 格式，经过足够的测试，以调试您自己的扩展 XSLT 转换。）

第一步，是在您的 C# 代码中加入您的自定义标记: (注意红色的自定义标记)

[C#]
/// <myTag>This is a custom tag</myTag>
/// <summary>
/// When processed by the VS.NET or MSDN documenters,
/// using the stylesheet "extend-ndoc.xslt" as the ExtensibilityStylesheet
/// property will result in end-user defined tags being displayed in the
/// final help output topics
/// </summary>
/// <remarks>This is a test of an inline <null/> tag</remarks>
public class ABunchOfCustomTags
{
}

在编译后生成的 /doc 文档中，您可以找到这些自定义的标记。

接下来，创建您的 XSLT 转换模板，控制那些自定义标记的输出位置和样式:

<xsl:stylesheet version="1.0" xmlns:xsl=http://www.w3.org/1999/XSL/Transform xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

<xsl:template match="node()" mode="xml-data-island" priority="1">

<MSHelp:Attr Name="TargetOS" Value="Windows"/>

</xsl:template>

<xsl:template match="ndoc" mode="header-section">

.green

{

color:green;

}

</style>

</xsl:template>
<xsl:template match="myTag" mode="seealso-section">

<h1 >

<xsl:value-of select="." mode="slashdoc"/>

</h1>

</xsl:template>

<xsl:template match="null" mode="slashdoc">

<xsl:text> null reference (Nothing in Visual Basic) </xsl:text>

</xsl:template>

</xsl:stylesheet>

您应该确认 XSLT 标记的完整和语法的正确，注意 XSLT namespace 是必须的。

如上面示例中看到的那样，使用 stylesheet 中的 templates“匹配(match)”您的自定义标记。match 是 XPath 查询的一种，指示 template 将应用于哪些标记。简单的用法是直接匹配您的自定义标记，当然还可以有更高级的用法，对 XSLT 高手们应当是小菜一碟。

注意: 如果您定义的自定义标记中还包含其他标记，您应当加入下面的命令，让它转换这些内含的标记(比如 <see> 等)：
<xsl:apply-templates select="." mode="slashdoc"/>
上例中还展示了向 HTML HEAD 头部添加附加样式定义的方法，即使用 mode 为 header-section 的 template。使用这种方法您可以覆盖 NDoc 默认的样式或者添加附加的样式表等。

什么是 mode 呢？mode 用于指定该内容将显示于文档的哪些区域。NDoc 扩展的自定义标记可以是以下两类:

Section 标记 - 块标记，将显示于文档的某个区域。为 section 标记编写 template 时，mode 必须是预定义的可用 Section 的列表中的一个。
Inline 标记 - 将和其他注释文本夹杂在一起。为 inline 标记编写 template 时，mode 必须是 "slashdoc"。
如果您准备编写匹配一些泛型 XPath 查询，如 node(), text(), *, 或 @*，您应当给该 template 指定一个名为 priority、值大于 0.5 的属性，用您编写的 template 替换 NDoc 默认的转换模板。

请注意: XSLT 是大小写敏感的，match 查询模式，以及 mode 值都必须使用正确的大小写，否则将被忽略。

最后，为 MSDN 或 VS.NET 文档引擎设置 ExtensibilityStylesheet 配置，指向您创作好的 XSLT 转换文件。然后使用 NDoc 生成代码文档，您将看到已经按照您编写的 template 规则执行了相应转换。

一张屏幕截图:

输出示例

可用 Section 的列表
下面列出了所有可用 section 的清单，它们用于 NDoc 扩展 XSLT 转换模板中 mode 属性的值，指示该标记将显示在代码文档中的区域。

Section 名称	说明
header-section	HTML 的 HEAD 区域。可以使用此区域添加附加的样式定义等。
preliminary-section	“预发布”警告区域。仅当注释文档中使用 <preliminary> 标记显式标出，或通过文档引擎的 Preliminary 配置为 true 时，才会显示该区域。
summary-section	<summary> 标记对应的区域。tag.
thread-safety-section	“线程安全”区域。
syntax-section	“语法”区域。
value-section	<value> 标记对应的“属性值”区域。
parameter-section	<param> 标记对应的“参数”区域。
returnvalue-section	<returns> 标记对应的“返回值”区域。
implements-section	“接口实现”区域。
remarks-section	<remarks> 标记对应的“备注”区域。
after-remarks-section	“备注”区域后的区域。注意: 不管“备注”区域是否存在，此区域总是存在的。
obsolete-section	“已过时”区域。
events-section	<event> 标记对应的“事件”区域。
exceptions-section	<exception> 标记对应的“异常”区域。
example-section <example>	标记对应的“示例”区域。
member-requirements-section	(某一个成员的)“要求”区域。
type-requirements-section	(类型的)“要求”区域。
seealso-section	“请参见”区域。
enumeration-members-section	“枚举成员”区域。
footer-row	页脚区域。
title-row	页眉区域。
overloads-remarks-section	重载页面的“备注”区域。
overloads-example-section	重载页面的“示例”区域。
overloads-summary-section	重载页面的“摘要”区域。
xml-data-island	HTML部嵌入的 XML 数据区域，可以附加自定义的元素或内容。仅对 VS.NET 2003 文档引擎有效。

实现一个新的文档引擎
　实现一个新的文档引擎至少需要编写两个类:

一个从 NDoc.Core.DocumenterBase 继承而来的类

一个从 NDoc.Core.DocumenterConfigBase 继承而来的类

DocumenterConfigBase 是用于存储文档引擎配置信息的基类。它已经包含了一些通用的配置项，这些通用配置主要用于配置 NDoc 中间 XML 数据文件的生成动作。您编写的子类可以添加所需要的特定配置项(比如生成的文档保存在什么路径下等)。

DocumenterBase 是文档引擎的基类。文档引擎的工作模式是，第一步生成 NDoc 中间 XML 数据文件，第二步由各文档引擎将中间 XML 数据文件、分别转换成所需的最终文档格式。此基类完成了第一步的工作，您编写的子类只需完成第二个步骤。

必须实现的成员包括 Clear, Build 方法以及 MainOutputFile 属性等抽象(abstract)成员。

实现 Build 方法时, 可以调用基类的 MergeXML 方法，它完成第一步的 NDoc 中间 XML 数据文件的合并和制作。

使用 XML 文档引擎可以导出一个 NDoc 中间 XML 数据文件的样例。您可以通过分析它，调试您的自定义转换代码或 XSLT 转换定义。使用 UseNDocXmlFile 配置项，可以节省您的调试时间。

文档引擎是如何加载的
　NDoc 通过反射发出(Reflection)机制动态分析和加载文档引擎。NDoc 启动时，自动检查程序(NDocGui.exe 或 NDocConsole.exe)所在路径中、所有以如下格式命名的程序集:

NDoc.Documenter.<NAME>.dll

其中 <NAME> 是文档引擎的名称(注: 可能与界面中显示的名称不同)。

NDoc 从这些程序集中分析、尝试查找 DocumenterBase 的子类，并加载找到的文档引擎。

为 NDoc 贡献代码
您可以有很多种选择，为 NDoc 的开发做出有益的贡献。

加入 ndoc-users 邮件列表是最简单的方式、和其他用户分享您的使用心得体会和经验。
如果您发现了 bug，或者有一些不错的新功能建议，请使用 NDoc tracker database，让我们了解您的发现和想法。
如果您有更多空闲的时间，希望成为 NDoc 开发组的成员、和我们一起实现那些 new features 或者修复那些已知的 bugs，请通过NDoc SourceForge 站点联络项目的负责人、管理员，我们会帮助您开始工作。我们欢迎越来越多的人们加入 NDoc 队伍！
感谢您使用 NDoc！

NDoc 用户邮件列表
　您也可以搜索 ndoc-users 邮件列表的存档邮件，或者发送问题到这个邮件列表。

NDoc 跟踪数据库
　如果通过以上途径还是没有找到您要的答案，您可以尝试 NDoc 在 SourceForge.net 维护的 Tracker database。

提交一个支持请求(support request)
提交 Bug 报告
提交新功能建议

介绍 NDoc 的文章
　网络中还有很多不错的 NDoc 介绍文章，下面有些文章发布时间很早，有些链接已经失效了。

[Documenting C# with XML comments], 作者 Ollie Cornes
[Using NDoc: Adding World-Class Documentation to Your .NET Components], 作者 Shawn Van Ness
[Fixing NDoc to emit links for Everett's MSDN docs], 作者 Shawn Van Ness
[Integrate NDoc HTML Help 2 in Visual Studio.NET], 作者 Fons Sonnemans
[Creating class documentation with NDoc], 作者 Rick Harris
[Integrating Help into Visual Studio.NET], 作者 Sune Trudslev

本文链接

.NET2.0/3.0/3.5区别和VS各个版本概览(转)

2011-05-20T01:56:00Z

随着VS2008的推出，.NET框架版本已经升级到了3.5。但是.net framework 3.0和3.5其核心部分还是.net2.0的东西，只不过在其基础上增加了一些个类库。以下这个图表可以很清楚的描述了3个版本框架的不同之处。

VS Studio开发工具在这几年的Release版本见下表

相应的

.NET的发展方向。

本文链接

使用Sandcastle Styles 来生成VS2008的帮助文档.

2011-05-17T09:29:00Z

1: 下载 Sandcastle Styles http://sandcastlestyles.codeplex.com/

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

3: 使用SandcastleGui.exe来生成帮助文件 C:\Program Files\Sandcastle\Examples\Generic\SandcastleGui.exe

4: 使用HTML Help Workshop生成CHM文件

本文链接

Scrum Works 1.84安装

2011-04-29T08:15:00Z

1 : 下载Scrum Works1.84,并下载jboss-4.0.4.GA.zip放入到同一个文件夹.

2 : 安装成功后，默认的端口是8080，如果想改为别的端口，需要打开文件：\Scrumworks\server\scrumworks\deploy\jbossweb-tomcat55.sar\server.xml文件进行修改。其他配置按系统默认的即可。

3 : 运行客户端

在浏览器中输入：http://localhost:8080/scrumworks/ 出现如下界面：

4 : 客户端支持两种模式：一种是客户端方式登录，点击<Launch Scrum Works Basic Desktop Client>运行客户端程序（需要java runtime支持），第一次运行的时候会提示输入<license Key>，可以到Scrum Works网站上下载一个。默认的用户名和密码是：administrator, password.

本文链接

SQL Server 2005 中删除重复记录

2011-04-11T01:57:00Z

我们在数据库开发和维护时由于各种原因,经常会产生重复数据,如果数据量比较大的话,会是一个很费事的工作,那么怎么能够迅速的删除这些无用的重复记录呢.

USE [master]
GO

if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[TestTD]'))
DROP TABLE TestTD

CREATE TABLE TestTD(ProductID INT, ProductName NVARCHAR(50),Unit NVARCHAR(50),Price MONEY)

INSERT INTO TestTD(ProductID,ProductName,Unit,Price) VALUES (1,'A','UnitA',1)
INSERT INTO TestTD(ProductID,ProductName,Unit,Price) VALUES (2,'B','UnitA',2)
INSERT INTO TestTD(ProductID,ProductName,Unit,Price) VALUES (3,'C','UnitA',3)
INSERT INTO TestTD(ProductID,ProductName,Unit,Price) VALUES (3,'C','UnitC',3)
INSERT INTO TestTD(ProductID,ProductName,Unit,Price) VALUES (4,'D','UnitD',4)

SELECT * FROM TestTD

--Remove Redundancy Records
DECLARE @AllCount INT

--检查是否有重复记录
SELECT RedundancyCount = COUNT(ProductID),
ProductID
INTO #CostItem
FROM TestTD
GROUP BY ProductID
HAVING COUNT(ProductID) > 1

SELECT @AllCount = COUNT(ProductID) FROM #CostItem

-- There are some Redundancy Records. Remove them.
IF @AllCount > 0
BEGIN
     DECLARE      @CurrentPosition        INT,
                        @DuplicateCount         INT,
                        @ProductID                INT

    SET @CurrentPosition = @AllCount
    SELECT SortOrder = ROW_NUMBER() OVER (ORDER BY ProductID),
   *
    INTO #T
    FROM #CostItem
    --循环删除
    WHILE @CurrentPosition > 0
    BEGIN

--取出有重复数据的ProductID和重复的个数
      SELECT @DuplicateCount = RedundancyCount,
      @ProductID = ProductID
      FROM #T WHERE SortOrder = @CurrentPosition

--利用rownumber来删除,使重复的数据只保留一条.
     ;WITH [CostItem_RowID] AS
    (SELECT ROW_NUMBER() OVER (ORDER BY @ProductID) AS ROWID, *
     FROM TestTD gwci WHERE gwci.ProductID = @ProductID)
     DELETE FROM [CostItem_RowID] WHERE ROWID < @DuplicateCount

     SET @CurrentPosition = @CurrentPosition - 1
    END

DROP TABLE #T
END

DROP TABLE #CostItem
SELECT * FROM TestTD

效果图

本文链接

第一章 C#语言基础(C# Language Elements)

2011-02-18T06:21:00Z

为什么你应该改变现在正在做的即使它是好的.答案就是你会变得更强.你改变工具或者是语言来让你更高效.如果不改变习惯将很难获取你的期望. 当C#这种新的语言与大家一些熟悉的语言比如C++和Java拥有很多的共同点是一件很困难的事情.回到旧的习惯是一件很容易的事情,不过大多数的就习惯还是好的. C#语言的设计者希望我们能够使用以前的语言的知识.不过他们也添加和修改了一些元素来提供更集成的通用语言运行时(CLR)及对组件开发提供了更好的支持.本章将讨论那些你应该改变的习惯.

本文链接

Effective C#: 50个细节提高你的C#[50 Specific Ways to Improve Your C#]

2011-02-18T06:16:00Z

最近发现了一般好书,叫Effective C#: 50 Specific Ways to Improve Your C#.[Effective C#: 50个细节提高你的C#],网上也有一些翻译,不过看着都不太准确,最近闲来有空,就一边学习一边翻译试试了.此内容只用于学习和讨论,如涉及版权问题,本人将删除内容.

第一章 C#语言基础(C# Language Elements)

Item 1: 尽可能的使用属性代替可访问的数据成员(Always Use Properties Instead of Accessible Data Members)

Item 2: 使用readonly代替const(Prefer readonly to const)

Item 3: 使用 is 或 as 去做类型转换(Prefer the is or as Operators to Casts)

本文链接

Item 6: Distinguish Between Value Types and Reference Types

2011-02-18T06:09:00Z

Item 6: Distinguish Between Value Types and Reference Types

本文链接