chm文档生成->Sandcastle使用帮助

1.介绍

Sandcastle是微软提供的开源的，用于生成.net文档帮助的工具。

源代码路径：https://github.com/EWSoftware/SHFB，进去后能找到Relase版本的路径（https://github.com/EWSoftware/SHFB/releases）

官方帮助文档:http://ewsoftware.github.io/SHFB

(其中xml的标签使用：http://ewsoftware.github.io/XMLCommentsGuide/)

2.安装

1.安装前关闭VS,直接点击安装包进行安装

3.开始

1.打开待生成文档的工程的xml输出

　　工程属性中的“生成-输出-xml文档文件”。生成一下，就会生成它的xml文档

2.创建工程

　　以vs2019为例，在解决方案中添加 Sandcastle Help File Builder Project

　　解决方案管理器中，选中Documentation Sources，右键”Add Documentation Sources”，选择目标工程的dll和xml文件，生成即可。

4.优化配置

1.工程属性中设置语言、标题等

　　例：默认为英文，改为中文。属性里的“Help File”

2.支持语言，生成的文件格式

　　默认支持的F#、VB，没什么用，可去掉勾选。

　　默认生成chm文件，其他格式也挺有用的。（mshc文件与VS的融合很好，选中内容按F1就可启动搜索，如果需要可勾上）

3.打开报警，把报警全解决掉。

　　这样才不会出现文档有的字段没有解释，解释与参数对不上等问题

　　文档应该只支持按///生成的那种注释

　　再搜索一下“></param>”，找到所有没给参数注释写内容的地方，处理掉

4.关闭命名空间注释的报警

　　命名空间一般都不给它注释的，因为往往多个文件用同一个命名空间，在哪里注释？但是不给它注释，默认情况下就会出现上图这样的。

解决办法：

　　工程属性中，Missing Tags，去掉“Namespace documentation”的勾选.

5.Xml文档注释

　　以下列出一部分在 Sandcstle 可用文档注释。如果需要获取全部可用文档注释，则请参考 C# XML 文档注释和 NDoc 标记。Sandcastle 支持所有 C# XML 文档注释和部分 NDoc 标记，暂不支持用户自定义标记。

标记	说明
<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>	表示方法被重载。

6.标签示例

　　具体参考代码中///注释标签形式

  1 using System;
  2 using System.Collections.Generic;
  3 using System.Text;
  4 using System.Data;
  5 using System.Data.SqlClient;
  6 using System.Data.OracleClient;
  7 using System.Data.Common;
  8
  9 namespace Heading.Data
 10 {
 11     /// <summary>
 12     /// 数据库类型
 13     /// </summary>
 14     public enum DbmsType
 15     {
 16         /// <summary>
 17         /// SqlServer
 18         /// </summary>
 19         SqlServer,
 20
 21         /// <summary>
 22         /// Oracle
 23         /// </summary>
 24         Oracle,
 25     }
 26
 27     /// <summary>
 28     /// 存放应用程序全局资源和公共函数的静态类。
 29     /// </summary>
 30     /// <remarks>
 31     /// <c>DataHelper</c> 包含对数据库的全局操作集合，包括打开和关闭连接、创建事务等。此类支持以下 Microsoft SQL Server 和 Oracle 版本。
 32     /// <list type="table">
 33     /// <listheader><item>Microsoft SQL Server 版本</item><description>Oracle 版本</description></listheader>
 34     /// <item><item><list type="bullet">
 35     /// <item>Microsoft SQL Server 2000</item>
 36     /// <item>Microsoft SQL Server 2005</item>
 37     /// <item>Microsoft SQL Server 2008</item>
 38     /// </list></item>
 39     /// <description><list type="bullet">
 40     /// <item>Oracle 8i</item><item>Oracle 9i</item><item>Oracle 10g</item><item>Oracle 11g</item>
 41     /// </list></description></item>
 42     /// </list>
 43     /// </remarks>
 44     /// <example>
 45     /// 以下示例展示如何使用 <c>DataHelper</c> 类执行数据库事务操作。
 46     /// <code lang="C#" source="SamplesCSharpDataHelper.cs" region="DataHelper" />
 47     /// <note type="caution">
 48     /// <para>
 49     /// 此类是静态类。可在应用程序全局范围内使用，在使用此类的任何方法之前，您必须先初始化 <c>DataHelper</c>.Connection 属性。
 50     /// 有关 Connection 属性的信息，请参见 <see cref="T:System.Data.Common.DbConnection" />。
 51     /// </para>
 52     /// </note>
 53     /// </example>
 54     /// <seealso cref="DbmsType" />
 55     public static class DataHelper
 56     {
 57         // 为数据库设置连接字符串。
 58         private static DbConnection connection;
 59
 60         /// <summary>
 61         /// 获取用于存储事务的 DbTransaction。
 62         /// </summary>
 63         public static DbTransaction Transaction { get { return transaction; } }
 64         private static DbTransaction transaction;
 65
 66         /// <summary>
 67         /// 获取或设置数据库连接。
 68         /// </summary>
 69         public static DbConnection Connection { get { return connection; } set { connection = value; } }
 70
 71         /// <summary>
 72         /// 获取或设置数据库连接类型。
 73         /// </summary>
 74         public static DbmsType ConnectionType
 75         {
 76             get { return connectionType; }
 77             set
 78             {
 79                 switch (value)
 80                 {
 81                     case DbmsType.Oracle:
 82                         CloseConnection();
 83                         connection = new OracleConnection();
 84                         break;
 85                     case DbmsType.SqlServer:
 86                         CloseConnection();
 87                         connection = new SqlConnection();
 88                         break;
 89                 }
 90                 connectionType = value;
 91             }
 92         }
 93         private static DbmsType connectionType;
 94
 95         /// <summary>
 96         /// 在指定的连接上下文中执行 SQL 命令。
 97         /// </summary>
 98         /// <param name="command">需要执行的 T-SQL 语句。</param>
 99         /// <returns>执行语句后影响的行数。</returns>
100         public static int ExecuteSqlCommand(string command)
101         {
102             RaiseConnectionNotOpenedException();
103             using (DbCommand cmd = Connection.CreateCommand())
104             {
105                 cmd.Transaction = transaction;
106                 cmd.CommandText = command;
107                 return cmd.ExecuteNonQuery();
108             }
109         }
110
111         /// <summary>
112         /// 在指定的连接上下文中执行 SQL 命令。
113         /// </summary>
114         /// <param name="command">需要执行的 T-SQL 语句。</param>
115         /// <param name="param">格式化字符串。</param>
116         /// <returns>执行语句后影响的行数。</returns>
117         public static int ExecuteSqlCommand(string command, params object[] param)
118         {
119             return ExecuteSqlCommand(string.Format(command, param));
120         }
121
122         /// <summary>
123         /// 在指定的连接上下文中执行 SQL 命令，并返回包含数据集的 DbDataReader。
124         /// </summary>
125         /// <param name="command">需要执行的 T-SQL 语句。</param>
126         /// <returns>存放执行结果的 DbDataReader。</returns>
127         public static DbDataReader ExecuteSqlReader(string command)
128         {
129             RaiseConnectionNotOpenedException();
130             using (DbCommand cmd = Connection.CreateCommand())
131             {
132                 cmd.Transaction = transaction;
133                 cmd.CommandText = command;
134                 return cmd.ExecuteReader();
135             }
136         }
137
138         /// <summary>
139         /// 在指定的连接上下文中执行 SQL 命令，并返回包含数据集的 DbDataReader。
140         /// </summary>
141         /// <param name="command">需要执行的 T-SQL 语句。</param>
142         /// <param name="param">格式化字符串。</param>
143         /// <returns>存放执行结果的 DbDataReader。</returns>
144         public static DbDataReader ExecuteSqlReader(string command, params object[] param)
145         {
146             return ExecuteSqlReader(string.Format(command, param));
147         }
148
149         /// <summary>
150         /// 打开数据库连接，如果连接已经打开，则不会再次打开。
151         /// </summary>
152         public static void OpenConnection()
153         {
154             if (connection != null && connection.State == ConnectionState.Closed)
155                 connection.Open();
156         }
157
158         /// <summary>
159         /// 关闭数据库连接。如果连接已经关闭，则不会再次关闭。
160         /// </summary>
161         public static void CloseConnection()
162         {
163             if (connection != null && connection.State == ConnectionState.Open)
164                 connection.Close();
165         }
166
167         /// <summary>
168         /// 开始一个 SQL 事务，并将 Transaction 属性设置为当前活动的 DbTransaction。
169         /// </summary>
170         public static void BeginTransaction()
171         {
172             RaiseConnectionNotOpenedException();
173             transaction = Connection.BeginTransaction();
174         }
175
176         /// <summary>
177         /// 回滚当前活动的 SQL 事务。
178         /// </summary>
179         public static void Rollback()
180         {
181             RaiseTransactionException();
182             transaction.Rollback();
183         }
184
185         /// <summary>
186         /// 提交当前活动的 SQL 事务。
187         /// </summary>
188         public static void Commit()
189         {
190             RaiseTransactionException();
191             transaction.Commit();
192             try
193             {
194                 transaction.Dispose();
195             }
196             finally { transaction = null; }
197         }
198
199         /// <summary>
200         /// 检查当前数据库连接是否存在指定的表。
201         /// </summary>
202         /// <param name="tableName">表名称。</param>
203         /// <returns>如果存在此对象则返回 true。否则返回 false。</returns>
204         public static bool TableExists(string tableName)
205         {
206             RaiseConnectionNotOpenedException();
207             string command = null;
208             switch (connectionType)
209             {
210                 case DbmsType.Oracle:
211                     command = @"SELECT 1 FROM user_objects WHERE UPPER(object_name) = UPPER('{0}') " +
212                         "AND object_type = 'TABLE'";
213                     break;
214                 case DbmsType.SqlServer:
215                     command = @"SELECT 1 FROM sysobjects WHERE Name = N'{0}' AND Type = N'U'";
216                     break;
217             }
218
219             using (DbDataReader dr = ExecuteSqlReader(command, tableName))
220             {
221                 return dr.HasRows;
222             }
223         }
224
225         /// <summary>
226         /// 检查当前数据库连接是否存在指定的存储过程。
227         /// </summary>
228         /// <param name="tableName">存储过程名称。</param>
229         /// <returns>如果存在此对象则返回 true。否则返回 false。</returns>
230         public static bool StoredProcedureExists(string tableName)
231         {
232             RaiseConnectionNotOpenedException();
233
234             string command = null;
235             switch (connectionType)
236             {
237                 case DbmsType.Oracle:
238                     command = @"SELECT 1 FROM user_objects WHERE UPPER(object_name) = UPPER('{0}') " +
239                         "AND object_type = 'FUNCTION' OR object_type = 'PROCEDURE'";
240                     break;
241                 case DbmsType.SqlServer:
242                     command = @"SELECT 1 FROM sysobjects WHERE Name = N'{0}' AND Type = N'P'";
243                     break;
244             }
245
246             using (DbDataReader dr = ExecuteSqlReader(command, tableName))
247             {
248                 return dr.HasRows;
249             }
250         }
251
252         private static void RaiseConnectionNotOpenedException()
253         {
254             if (Connection == null)
255                 throw new Exception("输据库连接对象未设置。");
256             if (Connection.State != ConnectionState.Open)
257                 throw new Exception("输据库连接对象未打开。");
258         }
259
260         private static void RaiseTransactionException()
261         {
262             if (transaction == null) throw new Exception("Transaction 属性没有初始化。请先调用 BeginTransaction。");
263         }
264
265         private static int InternalExecuteCommand(string command)
266         {
267             RaiseConnectionNotOpenedException();
268             using (DbCommand cmd = Connection.CreateCommand())
269             {
270                 cmd.Transaction = transaction;
271                 cmd.CommandText = command;
272                 return cmd.ExecuteNonQuery();
273             }
274         }
275
276         private static int InternalExecuteCommand(string command, params object[] param)
277         {
278             return InternalExecuteCommand(string.Format(command, param));
279         }
280
281         private static DbDataReader InternalExecuteReader(string command)
282         {
283             RaiseConnectionNotOpenedException();
284             using (DbCommand cmd = Connection.CreateCommand())
285             {
286                 cmd.Transaction = transaction;
287                 cmd.CommandText = command;
288                 return cmd.ExecuteReader();
289             }
290         }
291
292         private static DbDataReader InternalExecuteReader(string command, params object[] param)
293         {
294             return InternalExecuteReader(string.Format(command, param));
295         }
296     }
297 }

工程属性打开xml文档输出，并将生成的xml添加到Sandcastle工程中，生成Sandcastle工程就可以得到chm文档了！

 1 using System;
 2 using System.Collections.Generic;
 3 using System.Text;
 4 using System.Data;
 5 using System.Data.SqlClient;
 6 using System.Data.OracleClient;
 7 using System.Data.Common;
 8
 9 namespace Heading.Data
10 {
11     #region DataHelper
12
13     /// <summary>
14     /// 获取或设置数据库连接。
15     /// </summary>
16     public static DbConnection Connection { get { return connection; } set { connection = value; } }
17
18     /// <summary>
19     /// 在指定的连接上下文中执行 SQL 命令。
20     /// </summary>
21     /// <param name="command">需要执行的 T-SQL 语句。</param>
22     /// <returns>执行语句后影响的行数。</returns>
23     public static int ExecuteSqlCommand(string command)
24         {
25             RaiseConnectionNotOpenedException();
26             using (DbCommand cmd = Connection.CreateCommand())
27             {
28                 cmd.Transaction = transaction;
29                 cmd.CommandText = command;
30                 return cmd.ExecuteNonQuery();
31             }
32         }
33         private static void RaiseConnectionNotOpenedException()
34         {
35             if (Connection == null)
36                 throw new Exception("输据库连接对象未设置。");
37             if (Connection.State != ConnectionState.Open)
38                 throw new Exception("输据库连接对象未打开。");
39         }
40     #endregion

效果

-->The End 2020.7.6