65.9K
CodeProject 正在变化。 阅读更多。
Home

SQL XML 文档

Evaldas Jocys
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.59/5 (12投票s)

2007年11月12日

CPOL

5分钟阅读

viewsIcon

117489

downloadIcon

1409

如何创建和编译 SQL XML 文档注释。

引言

本文将帮助您选择合适的 SQL XML 文档格式，并协助您以最少的资源将这些注释转换为 Microsoft 帮助格式。

背景

如今，SQL 仍没有实用的、能经受时间考验的 XML 文档标准。我怀疑像“DBdoc”这样的现有解决方案是否会被微软采纳。我还没有看到 SQL 2008，但我可以猜测所有 SQL 对象都将通过 SQL 扩展属性进行注释，并且 SQL 存储过程的注释将类似于此：

--- <summary>
--- Insert new record into table.
--- </summary>
--- <param name="RecordId">Unique record Id.</param>
--- <param name="RecordGuid">Set Global Unique Identifier.</param>
--- <param name="SomeValue">Set record value.</param>
--- <param name="RecordEnabled" ref="dbo.CategoryTable.RecordEnabled" />
--- <returns>Unique Id of new record.</returns>
--- <remarks>
--- History:
---     2007-11-02 - Created by Smith.
---     2007-11-23 - Modified by Neo.
--- </remarks>
CREATE PROCEDURE [dbo].[solution_Category_InsertRecord] (
    @RecordId Int,
    @RecordGuid UniqueIdentifier,
    @SomeValue NVarChar(200),
    @RecordEnabled Bit
)
AS
-- Stored procedure starts here...

注意：“ref”属性可用于从表列的扩展属性中提取注释。

...而 XML 文档文件可以像这样：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyDbDocs</name>
    </assembly>
    <members>
        <member name="M:Database.Procedures.solution_Category_InsertRecord
                    (Int,UniqueIdentifier,NVarChar,Bit)">
            <summary>
            Insert new record into table.
            </summary>
            <param name="RecordId" type="Int" size="4">Unique record Id.</param>
        <param name="RecordGuid" type="UniqueIdentifier" size="16">
                    Set Global Unique Identifier.</param>
            <param name="SomeValue" type="NVarChar" size="200">Set record value.</param>
            <param name="RecordEnabled" type="Bit" size="1"
        ref="dbo.Globalization_Countries.RecordEnabled">
        Enable or disable record.</param>
            <returns>Unique Id of new record.</returns>
            <remarks>
History:
    2007-11-02 - Created by Smith.
    2007-11-23 - Modified by Neo.
</remarks>
        </member>
    <member>...

...这样就可以轻松地使用微软目前使用的工具进行编译。

要求

您需要安装以下 4 个免费工具

  1. Microsoft SQL Server Native Client

    它包含用于连接 Microsoft SQL Server 7.0、2000 或 2005 的原生代码 API（ODBC、OLE DB 和 ADO）的应用程序的运行时支持。SQL Native Client 的可再发行安装程序安装了运行时所需的客户端组件，以便利用新的 SQL Server 2005 功能，并可选地安装开发使用 SQL Native Client API 的应用程序所需的头文件。

  2. Microsoft SQL Server 2005 Management Objects Collection

    包括 SQL Server 2005 管理 API 的几个关键元素，包括 Analysis Management Objects (AMO)、Replication Management Objects (RMO) 和 SQL Server Management Objects (SMO)。开发人员和 DBA 可以使用这些组件以编程方式管理 SQL Server 2000/2005。

  3. Microsoft SandCastle

    用于从 .NET 程序集及其关联的 XML 注释文件创建 MSDN 风格文档的命令行界面 (CLI) 工具。

  4. CodePlex SandCastle Help File Builder

    Microsoft SandCastle 的图形用户界面 (GUI)。还包含基于命令行的工具，可自动生成帮助文件。

安装完这些工具后，请确保 Visual Studio 2005 项目的引用指向正确的文件。这些是默认位置：

  • Microsoft.SqlServer.Smo

    C:\Program Files\Microsoft SQL Server\90\SDK\Assemblies\Microsoft.SqlServer.Smo.dll

  • Microsoft.SqlServer.ConnectionInfo

    C:\Program Files\Microsoft SQL Server\90\SDK\Assemblies\Microsoft.SqlServer.ConnectionInfo.dll

Using the Code

从 SQL XML 文档转换为 CHM 帮助文件的过程可以分为以下几个步骤：

  1. 使用官方推荐的标签（参见上例）进行文档注释。
    我希望这些注释将来能得到 Microsoft SQL Server IDE 和 Microsoft SandCastle 等工具的全面支持。您可以在此处找到 .NET 的推荐标签。
  2. 启动“Visual Studio 2005 Command Prompt”，并使用随附的 DatabaseToXml 工具和 C# 编译器将 SQL XML 注释导出到 XML 文档文件。

    DatabaseToXml.exe -t -s localhost -d DatabaseName -c MyDbDocs.cs

csc /t:library /doc:MyDbDocs.xml MyDbDocs.cs /reference:
"JocysCom.Sql.XmlDocumentation.dll","%ProgramFiles%\Microsoft SQL Server\90\SDK\
Assemblies\Microsoft.SqlServer.Smo.dll"
  3. 使用 CodePlex SandCastle Help File Builder 编译帮助文件。
    • 运行 [开始] -> 所有程序 -> SandCastle Help File Builder -> SandCastle Help File Builder GUI。
    • 点击 [Add] 按钮，将 MyDbDocs.xml 文件添加到列表中。
    • 点击：Project Properties \ Dependencies \ (Collection) [...] 按钮
      并添加两个文件：
      1. JocysCom.Sql.XmlDocumentation.dll
      2. %ProgramFiles%\Microsoft SQL Server\90\SDK\Assemblies\Microsoft.SqlServer.Smo.dll
    • 从菜单中选择：Documentation -> Build Project
      您可以将帮助生成器项目保存为 MyDbDocs.shfb。
  4. Microsoft 帮助文件 Documentation.chm 将被创建，看起来会像这样：

    Screenshot - SqlXmlDocumentation1.jpg

请**注意**，结果不会是理想的（C# 与 SQL 数据混合），但您将清楚地知道方向。微软或其他人只需要更新 XSLT 模板，您就可以仅使用现有工具构建适当的 SQL 文档。这意味着，如果微软采用了与 C#、VB.NET、JavaScript... 相同的 XML 文档样式，那么您的注释在将来将是有效的，并且您将节省时间，而不是花费在转换上。

DatabaseToXml 选项

Jocys.com Database XML Comments Exporter 1.x 的选项

Jocys.com Database XML Comments Exporter 1.0.0.0
Creates XML Comments file and DLL Library from database.

Usage:

    DatabaseToXml [-f <SqlScript> | -d <DataBaseName>]
      [-t | -s <ServerName> -u <UserName> -p <Password>]
      [-c <CsFile>] [-g <SqlScript>] [-r <Pattern>]

    Source:
      -f <SqlScript>    Import from SQL Script through TempDatabase.
      -d <DataBaseName> Database name.

    Connection:
      -t                Use trusted connection.
      -s <ServerName>   SQL server name. Default: localhost
      -u <UserName>     Database username.
      -p <Password>     SQL password.

    Filter:
      -r <Pattern>      Filter procedures with regular expression pattern.

    Destination:
      -g <SqlScript>    Specifies SQL Script output file to generate.
      -c <CsFile>       Specifies C# code output file.

Examples:

    :: Export from Database.
    DatabaseToXml -d MyDatabase -t -c MyDatabase.cs

    :: Script SQL Stored procedures with parsed XML Comments.
    DatabaseToXml -d MyDatabase -t -g MyProcedures.sql

    :: Export XML from SQL Script file.
    :: Use trusted connection for 'TempDatabase'.
    DatabaseToXml -f MyScripts.sql -t -c MyDatabase.cs

    :: Export XML and exclude procedures with 'Globalization' inside name.
    DatabaseToXml -d MyDatabase -t -c MyDatabase.cs -r "^((?!Globalization).)*$"

关注点

  • 如果您有任何问题或建议，我很乐意扩展本文。
  • 请注意，DatabaseToXml 工具仅用于存储过程的注释。
  • 微软不保证会使用这种形式的注释，但我坚信这是微软最合乎逻辑的选择，因为所有语言（C#、VB.NET、JavaScript、SQL...）统一的注释格式将缩短开发和支持时间。（正如您所见，我现在可以重复使用现有工具来生成 MSDN 风格的帮助。）

历史

  • 2007-11-12 - 创建本文。
  • 2007-11-13 - DatabaseToXml 工具更新了“-g”选项，该选项允许将带有已解析（如果缺失则重新创建）XML 注释的 SQL 存储过程脚本化到 *.SQL 文件中。如果您想为存储过程自动生成 XML 注释，可以使用此选项。
  • 2007-11-20 - 添加了用于生成带有 SQL XML 文档头文件的 INSERT/UPDATE/SELECT/DELETE 存储过程的数据库工具。

    Screenshot - SqlXmlDocumentation2.jpg

    我通常使用此工具为 .NET DataSets 创建存储过程。

    Screenshot - SqlXmlDocumentation3.jpg

  • 2007-11-23 - DatabaseToXml 工具更新了“-a”选项。这有助于导出带有经典旧头文件的 XML 注释存储过程（以防有人因发布流程需要）。
    MyTemplate.txt contents:

/*******************************************************************
-- Project        : $at
-- Version        : $av
-- Process        : $ap
-- Function       : $af
-- Description    : $DocSummary
-- Procedure Name : $ProcedureName
-- File Name      : $ProcedureFile
********************************************************************
-- Change History
********************************************************************
**  Date:                By:                Change Description:
**  $ah
********************************************************************/

:: Export procedures with template header.
DatabaseToXml.exe -t -d MyDatabase -g MyDbScript.sql
 -a "MyTemplate.txt" -at "Company ProductName" -av 1.0.0.0
 -ah "2007-11-22 - Modified by John Smith" -ap "Process" -af "Function"

Note: You can use -a[a-z] CLI parameters for $a[a-z] template parameters
  • 2007-11-23 - DatabaseToXml 工具更新了“-fn”选项。这将在导出时修复 [dbo].[ProcedureName] 样式的过程名称。
  • 2007-12-04 - 丢失的屏幕截图已重新上传。DatabaseToXml 工具更新了未记录的“-ru”选项。导出过程时，此选项会将 NOLOCK 替换为 READUNCOMMITTED。
  • 2008-02-29 - 添加了 server.SetDefaultInitFields(typeof(StoredProcedure), true); 行以加快导出过程。现在默认返回所有属性，不会有额外的数据库往返。
  • 2008-04-15 - Windows 应用程序连接提供程序已更新为 Microsoft.SqlServer.Management.Common.ServerConnection，以便在 Vista 上正常工作。其他错误已修复。
  • 2008-04-17 - 现在已排除加密的过程（schmallaria 的建议）。

参考文献

注意：我修改并扩展了 Stephen Toub 的 XmlComments 类，以增加对 SQL 的支持。您可以从此处下载原始代码。

© . All rights reserved.