帮酷LOGO
0 0 评论
文章标签:DOC  Xml文档  

介绍

本文将帮助为将来选择合适的SQL XML文档格式,并帮助将这些注释转换为具有最少资源的Microsoft帮助格式。

背景

今天仍然没有有用的XML文档标准,它可以支持时间。 我怀疑"dbdoc"这样的当前解决方案将被微软采纳。 我没有看到 SQL 2008,但是可以猜测所有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>CREATEPROCEDURE [dbo].[solution_Category_InsertRecord] (
 @RecordIdInt,
 @RecordGuidUniqueIdentifier,
 @SomeValueNVarChar(200),
 @RecordEnabledBit)AS-- Stored procedure starts here... 

注:'ref'属性可以用于从表列扩展属性提取注释。

。和XML文档文件可以如下所示:

<?xmlversion="1.0"?><doc><assembly><name>MyDbDocs</name></assembly><members><membername="M:Database.Procedures.solution_Category_InsertRecord
 (Int,UniqueIdentifier,NVarChar,Bit)"><summary> Insert new record into table.
 </summary><paramname="RecordId"type="Int"size="4">Unique record Id.</param><paramname="RecordGuid"type="UniqueIdentifier"size="16"> Set Global Unique Identifier.</param><paramname="SomeValue"type="NVarChar"size="200">Set record value.</param><paramname="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个免费工具:

它包含使用本地代码 api ( ODBC,OLE DB和 ADO ) 连接到微软 SQL Server 7.0.2000或者 2005的应用程序运行时支持。 SQL本机客户机的可以再发行安装程序安装运行时所需的客户端组件,利用新的SQL Server 2005特性开发应用程序。

包括 SQL Server 2005管理API的几个关键元素,包括 Analysis Management对象( AMO )。复制管理对象( RMO ) 和 SQL Server 管理对象( SMO )。 开发人员和dba可以使用这些组件以编程方式管理 SQL Server 2000/2005.

用于从. NET 程序集创建msdn样式文档及其关联的XML注释文件的命令行 接口( adv。CLI ) 工具。

用于 SandCastle的图形化用户界面( GUI )。 还包含基于 命令行的工具,以自动方式构建帮助文件。

安装这些工具后,请确保 Visual Studio 2005项目引用指向正确的文件。 以下是缺省位置:

  • Microsoft.SqlServer.Smo

    C:Program FilesMicrosoft SQL Server90SDKAssembliesMicrosoft.SqlServer.Smo.dll

  • Microsoft.SqlServer.ConnectionInfo

    C:Program FilesMicrosoft SQL Server90SDKAssembliesMicrosoft.SqlServer.ConnectionInfo.dll

使用代码

从 SQL XML文档到CHM帮助文件的转换可以在以下步骤中进行处理:

  • 使用官方推荐标签( 请参阅上面的示例) 进行文档注释。
    我希望这些评论能够完全由微软 SQL Server IDE和微软SandCastle这样的工具支持。 你可以在这里找到. NET 的推荐标签。
  • 启动"Visual Studio 2005命令提示"并将SQL注释导出到包含 DatabaseToXml 工具和 C# 编译器的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 Server90SDK
AssembliesMicrosoft.SqlServer.Smo.dll"
  • SandCastle帮助文件生成器编译帮助文件。
  • 运行 [Start] -> 所有程序-> 沙沙堡帮助文件生成器:> - 帮助文件生成器 GUI。
  • 按 [Add] 按钮并将 MyDbDocs.xml 文件添加到列表。
  • 单击:项目属性相关性( 集合) [...] 按钮
    并添加两个文件:
  • JocysCom.Sql.XmlDocumentation.dll
  • %ProgramFiles%Microsoft Server90SDKAssembliesMicrosoft.SqlServer.Smo.dll
  • 从菜单中选择:文档-> 生成项目
    可以将帮助生成器项目保存为 MyDbDocs.shfb。
  • 将创建Microsoft帮助文件 Documentation.chm,它将如下所示:

Screenshot - SqlXmlDocumentation1.jpg

如果你有一个不理想的答案,那么你将有一个明确的观点,但你的标题。 by或者它的他人只需要更新XSLT模板,你可以只使用现有的工具来构建正确的SQL文档。 这意味着如果微软采用与 C#。VB.Net。javascript相同的XML文档样式。 以后你的评论将是有效的,你将节省时间,不花费在转换。

DatabaseToXml选项

Jocys.com 数据库XML注释导出器 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).)*$" 

Points of Interest

  • 如果你有一些问题或者建议,我将很乐意扩展这篇文章。
  • 请注意,DatabaseToXml 工具仅用于存储过程的注释。
  • Microsoft不会保证使用这种形式的评论,但我强烈认为,对于微软来说,这是最合理的方式,因为统一的注释格式将缩短开发和支持时间。 ( 就像你看到的,现在可以重用现有工具生成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 DataSet 创建存储过程,通常为:

    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 Lost丢失截图。 DatabaseToXml 工具更新为没有文档的" -ru"选项。 当导出过程到SQL脚本时,这里选项将用 READUNCOMMITTED 替换 NOLOCK
  • 2008-02-29 Added server.SetDefaultInitFields(typeof(StoredProcedure), true); 为了加快导出过程的速度。 现在所有属性将默认返回,并且不会对数据库进行额外的往返。
  • 2008-04-15 Windows 应用程序连接提供程序更新为 Microsoft.SqlServer.Management.Common.ServerConnection 为了在Vista上正常工作。 其他 Bug 固定。
  • 2008-04-17加密过程现在排除了( 来自schmallaria的建议)。

引用

注意:我已经修改和扩展了Toub类的Stephen XmlComments,以便添加SQL支持。 你可以从这里下载原始代码( 这里是 )。



文章标签:DOC  Xml文档  

Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语