今早下了两个工具【NDOC】 和 【Sandcastle】.
他们都是用来生成我们CS代码的帮助文档之用，生成的帮助文档类型有：Help1.x(*.chm) , Help2.0(Hxs)和网站（ASP.NET与HTML）。
他们都支持C# XML 文档注释和部分NDOC标记，暂不支持用户自定义标记。
C# XML 文档注释语法参考： http://msdn.microsoft.com/zh-cn/library/b2s063f7.aspx
标记语法部分如下：
| 标记 | 说明 |
| <a> |
<a href="url">Sample</a>表示一个超级链接。 |
| <b> | <b>...</b> 表示加粗。 |
| <c> | <c>...</c> 代码引用。 |
| <code> | <code [ lang="VB | VB.NET | C# | C++ | J#" source="path" region="region" ]>...</code> 表示一段代码引用。 |
| <example> | <example>...</example> 表示示例。 |
| <note> | <note type="caution | implementnotes | callers | inheriters">...</note> 表示备注。 |
| <list> | <list type="bullet | number | table">...</list> 表示一个列表。 |
| <para> | <para> 表示一个段落。 |
| <param> | <param name="">...</param> 表示参数说明。 |
| <paramref> | <paramref cref="" /> 表示一个参数的引用。 |
| <summary> | <summary> 表示摘要。 |
| <typeparam>, <typeparamref> | <typeparam name="T"> 表示一个类型参数。 |
| <event> | <event> 表示方法触发的一个事件说明。 |
| <remarks> | <remarks> 表示额外的备注。 |
| <threadsafety> | <threadsafety instance="true | false" static="true | false"> 表示线程安全说明。 |
| <value> | <value> 表示属性的值说明。 |
| <returns> | <returns type="type"> 表示方法的返回值说明。 |
| <preliminary> | 表示该文档是预发行版本。 |
| <overload> | 表示方法被重载。 |
结合示例参考关于XML文档注释语法：
using System;
using System.Collections.Generic;
using System.Text;
using System.Data;
using System.Data.SqlClient;
using System.Data.OracleClient;
using System.Data.Common;
namespace Heading.Data
{
/// <summary>
/// 存放应用程序全局资源和公共函数的静态类。
/// </summary>
/// <remarks>
/// <c>DataHelper</c> 包含对数据库的全局操作集合，包括打开和关闭连接、创建事务等。此类支持以下 Microsoft SQL Server 和 Oracle 版本。
/// <list type="table">
/// <listheader><item>Microsoft SQL Server 版本</item><description>Oracle 版本</description></listheader>
/// <item><item><list type="bullet">
/// <item>Microsoft SQL Server 2000</item>
/// <item>Microsoft SQL Server 2005</item>
/// <item>Microsoft SQL Server 2008</item>
/// </list></item>
/// <description><list type="bullet">
/// <item>Oracle 8i</item><item>Oracle 9i</item><item>Oracle 10g</item><item>Oracle 11g</item>
/// </list></description></item>
/// </list>
/// </remarks>
/// <example>
/// 以下示例展示如何使用 <c>DataHelper</c> 类执行数据库事务操作。
/// <code lang="C#" source="Code SamplesCSharpDataHelper.cs" region="DataHelper" />
/// <code lang="VB.NET" title="Visual Basic" source="Code SamplesVBDataHelper.vb" region="DataHelper" />
/// <code lang="C++" source="Code SamplesC++DataHelper.cpp" />
/// <note type="caution">
/// <para>
/// 此类是静态类。可在应用程序全局范围内使用，在使用此类的任何方法之前，您必须先初始化 <c>DataHelper</c>.Connection 属性。
/// 有关 Connection 属性的信息，请参见 <see cref="T:System.Data.Common.DbConnection" />。
/// </para>
/// </note>
/// </example>
/// <seealso cref="DbmsType" />
public static class DataHelper
{
// 为数据库设置连接字符串。
private static DbConnection connection;
/// <summary>
/// 获取用于存储事务的 DbTransaction。
/// </summary>
public static DbTransaction Transaction { get { return transaction; } }
private static DbTransaction transaction;
/// <summary>
/// 获取或设置数据库连接。
/// </summary>
public static DbConnection Connection { get { return connection; } set { connection = value; } }
/// <summary>
/// 获取或设置数据库连接类型。
/// </summary>
public static DbmsType ConnectionType
{
get { return connectionType; }
set
{
switch (value)
{
case DbmsType.Oracle:
CloseConnection();
connection = new OracleConnection();
break;
case DbmsType.SqlServer:
CloseConnection();
connection = new SqlConnection();
break;
}
connectionType = value;
}
}
private static DbmsType connectionType;
/// <summary>
/// 在指定的连接上下文中执行 SQL 命令。
/// </summary>
/// <param name="command">需要执行的 T-SQL 语句。</param>
/// <returns>执行语句后影响的行数。</returns>
public static int ExecuteSqlCommand(string command)
{
RaiseConnectionNotOpenedException();
using (DbCommand cmd = Connection.CreateCommand())
{
cmd.Transaction = transaction;
cmd.CommandText = command;
return cmd.ExecuteNonQuery();
}
}
/// <summary>
/// 在指定的连接上下文中执行 SQL 命令。
/// </summary>
/// <param name="command">需要执行的 T-SQL 语句。</param>
/// <param name="param">格式化字符串。</param>
/// <returns>执行语句后影响的行数。</returns>
public static int ExecuteSqlCommand(string command, params object[] param)
{
return ExecuteSqlCommand(string.Format(command, param));
}
/// <summary>
/// 在指定的连接上下文中执行 SQL 命令，并返回包含数据集的 DbDataReader。
/// </summary>
/// <param name="command">需要执行的 T-SQL 语句。</param>
/// <returns>存放执行结果的 DbDataReader。</returns>
public static DbDataReader ExecuteSqlReader(string command)
{
RaiseConnectionNotOpenedException();
using (DbCommand cmd = Connection.CreateCommand())
{
cmd.Transaction = transaction;
cmd.CommandText = command;
return cmd.ExecuteReader();
}
}
/// <summary>
/// 在指定的连接上下文中执行 SQL 命令，并返回包含数据集的 DbDataReader。
/// </summary>
/// <param name="command">需要执行的 T-SQL 语句。</param>
/// <param name="param">格式化字符串。</param>
/// <returns>存放执行结果的 DbDataReader。</returns>
public static DbDataReader ExecuteSqlReader(string command, params object[] param)
{
return ExecuteSqlReader(string.Format(command, param));
}
/// <summary>
/// 打开数据库连接，如果连接已经打开，则不会再次打开。
/// </summary>
public static void OpenConnection()
{
if (connection != null && connection.State == ConnectionState.Closed)
connection.Open();
}
/// <summary>
/// 关闭数据库连接。如果连接已经关闭，则不会再次关闭。
/// </summary>
public static void CloseConnection()
{
if (connection != null && connection.State == ConnectionState.Open)
connection.Close();
}
/// <summary>
/// 开始一个 SQL 事务，并将 Transaction 属性设置为当前活动的 DbTransaction。
/// </summary>
public static void BeginTransaction()
{
RaiseConnectionNotOpenedException();
transaction = Connection.BeginTransaction();
}
/// <summary>
/// 回滚当前活动的 SQL 事务。
/// </summary>
public static void Rollback()
{
RaiseTransactionException();
transaction.Rollback();
}
/// <summary>
/// 提交当前活动的 SQL 事务。
/// </summary>
public static void Commit()
{
RaiseTransactionException();
transaction.Commit();
try
{
transaction.Dispose();
}
finally { transaction = null; }
}
/// <summary>
/// 检查当前数据库连接是否存在指定的表。
/// </summary>
/// <param name="tableName">表名称。</param>
/// <returns>如果存在此对象则返回 true。否则返回 false。</returns>
public static bool TableExists(string tableName)
{
RaiseConnectionNotOpenedException();
string command = null;
switch (connectionType)
{
case DbmsType.Oracle:
command = @"SELECT 1 FROM user_objects WHERE UPPER(object_name) = UPPER('{0}') " +
"AND object_type = 'TABLE'";
break;
case DbmsType.SqlServer:
command = @"SELECT 1 FROM sysobjects WHERE Name = N'{0}' AND Type = N'U'";
break;
}
using (DbDataReader dr = ExecuteSqlReader(command, tableName))
{
return dr.HasRows;
}
}
/// <summary>
/// 检查当前数据库连接是否存在指定的存储过程。
/// </summary>
/// <param name="tableName">存储过程名称。</param>
/// <returns>如果存在此对象则返回 true。否则返回 false。</returns>
public static bool StoredProcedureExists(string tableName)
{
RaiseConnectionNotOpenedException();
string command = null;
switch (connectionType)
{
case DbmsType.Oracle:
command = @"SELECT 1 FROM user_objects WHERE UPPER(object_name) = UPPER('{0}') " +
"AND object_type = 'FUNCTION' OR object_type = 'PROCEDURE'";
break;
case DbmsType.SqlServer:
command = @"SELECT 1 FROM sysobjects WHERE Name = N'{0}' AND Type = N'P'";
break;
}
using (DbDataReader dr = ExecuteSqlReader(command, tableName))
{
return dr.HasRows;
}
}
private static void RaiseConnectionNotOpenedException()
{
if (Connection == null)
throw new Exception("输据库连接对象未设置。");
if (Connection.State != ConnectionState.Open)
throw new Exception("输据库连接对象未打开。");
}
private static void RaiseTransactionException()
{
if (transaction == null) throw new Exception("Transaction 属性没有初始化。请先调用 BeginTransaction。");
}
private static int InternalExecuteCommand(string command)
{
RaiseConnectionNotOpenedException();
using (DbCommand cmd = Connection.CreateCommand())
{
cmd.Transaction = transaction;
cmd.CommandText = command;
return cmd.ExecuteNonQuery();
}
}
private static int InternalExecuteCommand(string command, params object[] param)
{
return InternalExecuteCommand(string.Format(command, param));
}
private static DbDataReader InternalExecuteReader(string command)
{
RaiseConnectionNotOpenedException();
using (DbCommand cmd = Connection.CreateCommand())
{
cmd.Transaction = transaction;
cmd.CommandText = command;
return cmd.ExecuteReader();
}
}
private static DbDataReader InternalExecuteReader(string command, params object[] param)
{
return InternalExecuteReader(string.Format(command, param));
}
}
}
__________打下以上基础后，我们再了解这些工具的由来，以及如何使用他们。做的更好的话，我们还可以关注如何将这些工具集成到VSS平台_______
C#编程工具列表： http://msdn.microsoft.com/zh-cn/library/aa336818.aspx#buildtools
工具由来篇：
这两个工具应该说NDOC是始祖，Sandcastle是2006年微软发布的一个工具，他通过反射程序集中的源代码以及添加代码中的XML注释来创建MSDN形式的API文档。目前发布的最新版本是【1.8.0.1 Beta】，访问地址 ： http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=18639 （在这里你可以下载到安装工具和源码程序）
微软的Sandcastle首次公开露面是在2006年，他的开发周期已经超过了2年。当时微软宣布要建立Sandcastle项目后，NDOC团队就停止了NDOC项目的继续开发了（估计是斗不过Microsoft）,但是之后还是有很多热心人士在NDOC的基础上开发了“NDOC2005”和“NDOC3”等，最近有出来了“NDOC2007”，这个版本支持“.NET2.0”代码程序以及中、英文XML注释，而且如果你程序里面引用了第三方插件的话，他也能成功的跨越并编译通过（好像是第一次失败，第二次成功）。
NDOC2007下载地址：1： http://download.csdn.net/source/898171
2： http://blog.vckbase.com/Files/BastEt/ndoc2007.rar
由于早上工作内容要处理，下面的文章待续，（接下来大概要写，如何使用这些工具，以及如何集成这些工具来开发 。。。。）
浙公网安备 33010602011771号