chm文档生成->Sandcastle使用帮助
2024-10-21 03:47:40
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
最新文章
- Hibernate操作指南-实体与常用类型的映射以及基本的增删改查（基于注解）
- jQuery Length属性
- OpenCV学习笔记（一）——OpenCV安装
- HDU 1839
- ng-template寄宿方式
- Teredo 是一项 IPv6/IPv4 转换技术
- highcharts报表插件之expoting参数的使用
- Linux--/tmp目录文件重启后自动删除
- ActionBarCompat
- NUnit - 使用感受
- Javascript兑现图片预加载【回调函数，多张图片】 (转载)
- 利用phpcms-v9站群功能建立多个分站
- C++三种野指针及应对／内存泄露
- db2 常见错误以及解决方案[ErrorCode SQLState]
- 训练赛-Eyad and Math
- JS进阶之---函数，立即执行函数
- python：'ascii' codec can't encode character
- GUI程序设计
- Multiline ComboBox
- andorid手机电脑操作