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.标签示例

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

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>
    public enum DbmsType
    {
        /// <summary>
        /// SqlServer
        /// </summary>
        SqlServer,

        /// <summary>
        /// Oracle
        /// </summary>
        Oracle,
    }

    /// <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="SamplesCSharpDataHelper.cs" region="DataHelper" />
    /// <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));
        }
    }
}

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

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
{
    #region DataHelper

    /// <summary>
    /// 获取或设置数据库连接。
    /// </summary>
    public static DbConnection Connection { get { return connection; } set { connection = value; } }

    /// <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();
            }
        }
        private static void RaiseConnectionNotOpenedException()
        {
            if (Connection == null)
                throw new Exception("输据库连接对象未设置。");
            if (Connection.State != ConnectionState.Open)
                throw new Exception("输据库连接对象未打开。");
        }
    #endregion

效果

 

 

 

 -->The End 2020.7.6