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

DocMounter 2：一个用于构建 VS.NET 文档的工具（现已集成 Sandcastle）

10Tec
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.94/5 (28投票s)

2010年11月3日

GPL3

14分钟阅读

viewsIcon

148234

downloadIcon

1410

用于创建 MS Visual Studio 文档文件 - XML 摘要、HxS/MSHC 帮助解决方案和手册的工具。

Screenshot_DocMounter.png

目录

简要介绍

从 Visual Studio .NET 的早期版本开始，就可以在代码中直接记录类并创建标准的文档部分（如摘要、备注、参数描述等），其中包含标准标签。但对于我们开发者来说，直接在代码中完整地记录类和创建像备注这样长的部分是非常不方便的。当文档由技术文档撰写者创建，而代码由开发人员创建时，情况会更糟；他们同时处理同一个源文件并不太合适。

我们在开发第一个 .NET 组件时也遇到了所有这些问题。我们决定通过创建自己的工具来解决它们，并将其命名为“DocMounter”。DocMounter 成为了一个将代码与文档分离的工具，同时不损失 Visual Studio 提供的便利性，甚至更多。该工具逐步改进，最终成为一个易于使用的应用程序，可能对其他开发者有所帮助。当前版本实现了许多标准 VS XML 文档技术无法提供的实用功能。

CodeProject 已经有一篇关于我们工具第一个版本的帖子（请参阅本文），但我们决定发布一篇新的文章，介绍我们最近发布的下一代工具。该工具几乎在 80% 的地方进行了重写，现在几乎是一个全新的工具（尽管我们试图保持视觉简洁的理念），因此我们认为该工具值得一篇新文章。

主要功能

DocMounter 允许您执行以下任务

  1. 通过其可视化界面输入类及其成员的所有标准部分，如摘要、备注、示例、参见等。

  2. 通过方便的插入标签对话框添加标准 XML 文档标签，如 see、code、list、table 等。

  3. 使用与类及其成员相同的语法（XML 文档语法）创建附加主题。

  4. 管理项目节点，即未来帮助文件的目录结构。

  5. 在支持语法高亮、可自定义拼写检查和代码折叠的编辑器窗口中查看和编辑主题的源文件。

  6. 使用与类及其成员相同的语法创建概念主题（与特定类或其成员无关）。

  7. 生成标准的 XML 文档文件，这些文件可用于支持它的任何工具和开发环境（包括所有版本的 Visual Studio .NET）。

  8. 从所有附加主题生成单个 HTML 文件。之后，可以稍作编辑，将此文件转换为 DOC、RTF 或 PDF 格式，并用作手册。

  9. DocMounter 的内部可扩展模型允许集成外部文档编译器（如 NDoc 或 SandCastle），以生成所需的输出文档。

简洁、简洁，还是简洁

有一些开源项目用于构建文档，例如过时的 NDoc 和现代的 SandCastle 文档编译器，但如果您尝试使用它们，您会知道如何根据您的实际需求使其正常工作。当我们在设计 DocMounter 时，简洁性是该产品的主要特点之一，现在我们有一个绝佳的工具，您可以在部署后立即使用它，只需单击一下即可构建帮助解决方案。

尽管 DocMounter 简洁，但它拥有构建功能齐全的 XML 文档和帮助文件所需的所有工具。如前所述，我们在公司广泛使用它来记录我们的 .NET 产品。全世界许多开发人员也发现此工具对他们的项目非常有价值。

DocMounter 2 和 Sandcastle

此版本的 DocMounter 使用一个免费的开源文档编译器 Sandcastle，微软团队也使用它来创建 MSDN 库。这意味着您将获得与 MSDN 中相同的 HxS 文档外观和感觉，这是微软自 VS 2005 发布以来使用的。要了解更多关于 Sandcastle 的信息，请访问该项目的首页：http://sandcastle.codeplex.com/。

Sandcastle 需要单独下载和配置，如手册所述，但我们的 DocMounter 包也包含对原始 Sandcastle 安装的一些小的增强和修正，以便在某些地方具有更好的功能和外观。所有这些增强功能都将在构建过程中由 DocMounter 自动应用，因此您无需手动执行任何操作。

安装和系统要求

DocMounter 分发为使用 .NET Framework 4.0 构建的便携式 exe 应用程序，但要能够构建和查看您的 HxS 解决方案，您需要安装一些 Microsoft 工具。这些工具包括 HxReg.exe（用于注册帮助命名空间）和 HxComp（用于将 HTML 编译成 HxS 帮助解决方案）。它们包含在 VS 2005/2008 SDK 中，您需要安装它才能使用 DocMounter 的所有功能。

在使用 DocMounter 之前，请仔细阅读随附的 DocMounter 手册 PDF 文档中的“安装和系统要求”部分。这是一个全面的指南，解释了 DocMounter 需要哪些外部工具、在哪里获取它们以及如何安装和配置这些工具。

轻松上手

要记录您的 .NET 库，请使用“文件\新建项目”菜单命令创建一个新项目。将显示一个文件打开对话框 - 在其中选择所需的程序集。选择一个或多个程序集并单击“打开”按钮后，将创建项目。您会发现主题树包含您的程序集中定义的所有命名空间。您的项目已准备就绪 - 您可以展开节点，选择成员并在右侧的编辑器窗格中为它们编写描述。

要构建您的项目，只需单击工具栏上的“构建并查看 HxS”按钮。您的第一个 HxS 文件将在一分钟内创建，并在 Microsoft Document Explorer 中自动显示。您将在工具底部打开的“输出”窗格中看到构建过程的完整日志，其中包含所有可能的警告和错误消息。

描述类及其成员

DocMounter 允许您描述程序集的所有公共成员。加载项目或创建新项目后，您可以在 DocMounter 主窗口左侧的成员树中看到项目程序集的所有成员。在成员树中选择一个成员时，其描述部分会显示在成员树的右侧。每种类型的成员都有自己的部分集。有些部分对所有成员类型都是通用的（例如，Summary 部分存在于每种成员类型中）。编译帮助解决方案后，这些部分将被收集到一个主题中。

Screenshot_OutputHxS.png

您可以向部分描述中输入任何文本，它将直接传输到输出主题。此外，此文本可能包含特殊标签。这些标签允许您引用其他类型和成员，创建表格和列表等。这些标签非常类似于 Visual Studio .NET 中用于记录类及其成员的标签。您可以在以下文章中找到更多关于微软支持的标签的信息：

文档注释的推荐标签（C# 编程指南）

您可以在主题编辑器中直接输入标签，但这又是 DocMounter 极大简化您工作的一个地方。使用方便的“插入标签”对话框来完成此操作。

Screenshot_InsertTag.png

在表单的左侧，您可以看到 DocMounter 支持的所有标签的完整列表。其中一些标签不被微软 XML 文档语言支持，因为它们是 DocMounter 的特殊标签，用于扩展标准的 XML 文档功能。当您从列表中选择一个标签时，反映标签参数的字段将出现在表单的右侧。填写这些字段，然后按 OK 按钮。标签将被插入到描述中。

示例

例如。让我们为以下简单的 Class1 类（VB.NET 语法）创建一个摘要：

Public Class Class1
    Public Sub Method1()

    End Sub

    Public Sub GenericMethod(Of T)()

    End Sub
End Class

让我们写下我们类中最有用的方法 Method1，它执行主要工作，并插入一个交叉引用链接，看起来像这样：

Screenshot - Class1 Summary.png

好了，打开 DocMounter，加载包含这个简单类的 DLL 进行记录，然后单击代表 Class1 类的节点。在右侧的编辑器窗格中，输入我们描述的所有单词，除了最后一个单词“Method1”。要插入对 Method1 的交叉引用链接，请打开“插入标签”对话框，然后双击该成员以插入对它的引用链接。

Screenshot - Class1 Insert Tag

它将看起来像我们在以下屏幕截图中看到的那样。

Screenshot - Class1 Edit

就这样。单击“构建并查看 HxS”。一分钟后，我们就得到了想要的结果。

Screenshot - Class1 Output

就这些。甚至不需要学习 MS XML 文档标签集或 Sandcastle 的 MAML 语言中的特殊标签。请注意，您实际上是按原样输入您的描述 - 在您需要的特定语言中，例如，使用 <para> 标签创建段落，这会使我们的文本外观不太吸引人。MAML 还要求将您有用的用户文本包装到具有特殊预定义结构的 XML 文档中，但在 DocMounter 中，您只处理自定义描述。

创建和管理概念主题

除了成员描述，DocMounter 还允许您创建所谓的概念主题，这些主题与特定成员无关。这些主题的内容不包含在完整的 XML 和带有摘要的 XML 中，但这些主题包含在帮助解决方案中。通常，这些主题用于描述您产品的核心思想和概念。

要创建概念主题，请使用“节点”菜单或项目主题树的上下文菜单中的相应命令。之后，您可以重命名主题并重新排序它们。重新排序概念主题时，您也可以更改它们的层次结构。

当您编辑概念主题的内容时，您使用的 DocMounter 标签集与记录成员主题时使用的标签集相同。这是 DocMounter 帮助您的又一个地方。像 Sandcastle 这样的工具要求使用另一种语言（Sandcastle 的情况是 MAML），但在 DocMounter 中，您可以使用相同的“插入标签”对话框，甚至可以从成员主题复制准备好的主题内容部分到概念主题，反之亦然。

使用的代码技术

这个复杂的工具内部使用了数十种 .NET 技术。其中包括对磁盘和内存中的 XML 文档进行操作（包括 XSLT 转换和 XPath 查询）、线程（构建帮助解决方案时 - 它们在单独的线程中构建，并且可以停止构建过程）、处理项目节点时的面向对象方法等。

如果您下载此工具的源代码并进行检查，您会发现许多 .NET 技术的示例。无论如何，我们希望在下面的文章中重点介绍几个有趣的内部方法。

帮助编译器作为插件

DocMounter 1.x 使用 NDoc 作为其帮助编译器，Sandcastle 是 DocMounter v2 的编译器。但这些工具并没有硬编码到 DocMounter 代码中。事实上，我们通过 IHelpBuilder 接口很容易地将外部帮助编译器连接到接口部分。以下是此接口的主要组件：

public interface IHelpBuilder
{
  // When implemented in a derived class, generates the help from the specified assemblyFiles.
  // This method is invoked after the complete xml assemblyFiles
  // are formed and before building the topics.
  void BuildHelp(
    string[,] assemblyFiles,
    string outputDirPath,
    string mediaDirPath,
    string helpNamespace,
    string name,
    string title,
    string companyName,
    string version,
    string feedbackEmail,
    string docSetList,
    ConceptualTopic[] conceptualTopics,
    string conceptualTopicXmlsDirPath, 
    ProcessStepDelegate processStepCallback,
    Func shouldStopCallback);

  // When implemented in a derived class, shows the 
  // result of the last compilation.
  void ViewResult(string outputDirPath, string name, string helpNamespace);

  // When implemented in a derived class, indicates
  // whether the help builder can view the result.
  bool CanViewResult(string outputDirPath, string name);
}

您需要做的就是在一个 DLL 中实现 IHelpBuilder，然后它就可以作为 DocMounter 的插件来编译您的项目。

在可取消的单独线程中构建项目

DocMounter 的所有长时间构建过程都在单独的线程中执行，因此用户可以使用界面元素中断它们。看看我们如何启动 HxS 构建过程：

ProjExecuteInBkThread(new MethodInvoker(ProjBuildHxSBkThread), viewHxSAfterBuild);

构建 XML 摘要界面命令也是如此。

ProjExecuteInBkThread(new MethodInvoker(ProjBuildXmlSummariesBkThread), false);

正如您所见，控件已传递给 ProjExecuteInBkThread 方法。

private void ProjExecuteInBkThread(MethodInvoker mehtodToExecuteInBkThread, bool viewHxSAfterBuild)
{
  #region Check the arguments

  if (mehtodToExecuteInBkThread == null)
    new ArgumentNullException("mehtodToExecuteInBkThread");

  #endregion

  fMehtodToExecuteInBkThread = mehtodToExecuteInBkThread;
  fViewHxSAfterBuild = viewHxSAfterBuild;

  BuildDisableAllControlsExceptOutput();
  StartProcessingOutput();
  AdjustStopBuildControls(true);

  Thread myThread = new Thread(new ThreadStart(ProjExecutionThreadProc));
  myThread.IsBackground = true;

  myThread.Start();
}

线程中的主要工作在 ProjExecutionThreadProc 中完成。

private void ProjExecutionThreadProc()
{
#if !DEBUG
  try
  {
#endif
    lock (this)
    {
      fExecutionWasAborted = false;
    }

    if (fMehtodToExecuteInBkThread != null)
      fMehtodToExecuteInBkThread();

    lock (this)
    {
      if (fExecutionWasAborted)
        MessagesManager.ShowError(this, "Execution was aborted.");
    }
#if !DEBUG
  }
  catch (Exception ex)
  {
    MessagesManager.ShowError(this, "Unable to perform operation: " + ex.Message);
  }
  finally
  {
#endif
    Invoke(new MethodInvoker(BuildEnableAllControls));
    Invoke(new Action(AdjustStopBuildControls), false);
    Invoke(new MethodInvoker(AdjustInsertTagControls));
    Invoke(new MethodInvoker(AdjustHxSControls));
    if (fViewHxSAfterBuild)
      Invoke(new MethodInvoker(ProjViewHxS));
#if !DEBUG
  }
#endif
}

这是我们线程模型的“核心”。它允许我们 (1) 启动任何构建过程，(2) 在需要时中断它，(3) 捕获意外的错误，从而使整个工具保持稳定且不会崩溃。请注意，最后一点仅在发布版本中有效 - 在 VS IDE 中开发工具时，我们仍然能够在调试器中停止在异常处。如果我们不使用条件编译 DEBUG 常量，在调试时我们会得到一个通用的（但对用户友好，对开发人员不友好）错误消息，而不是直接在 IDE 中突出显示导致异常的语句。

这种思想可以用于我们能够发明并纳入 DocMounter 的任何新构建过程 - 现在我们将只关注新构建过程的核心功能。

总结：DocMounter 的主要优点

在简短的介绍性文章之后，让我们列出该工具的所有主要优点，以便您对该工具的功能以及它如何节省您的时间有一个总体感觉。

  1. DocMounter 最重要的好处是您的代码和描述在不同的地方，因此您的代码不会因为源文件中的文档而臃肿（这是您在 Visual Studio 中得到的结果）。这也允许两个人同时独立地进行产品开发及其文档工作（开发人员和技术文档撰写者）。

  2. Visual Studio 不允许您创建概念文档，因为您只能在源文件代码中记录成员，但在 DocMounter 中，您可以创建此类帮助主题。

  3. DocMounter 不仅允许您构建一个具有概念主题树状结构的交互式 HxS 文件，还可以构建一个可打印的手册，其中所有概念主题都逐个放置。

  4. DocMounter 生成的文档外观和感觉与 MSDN 中看到的一样。

  5. DocMounter 具有直观的用户界面，非常简单，但其功能涵盖了您编写帮助解决方案所需的所有主要功能。

  6. 在 DocMounter 中，您在一个统一的界面中使用相同的原理和标签集编写概念主题和成员主题。DocMounter 提供了一个方便的可视化“标签插入”对话框，而不是手动编写标签，这为您节省了大量时间。

  7. 帮助主题在 DocMounter 的主题编辑器中几乎以纯文本形式编写（您只编写有用的内容），它们会自动编译成功能齐全的最终帮助页面，这些页面使用相同的视觉和功能模板。

  8. 如果正在记录的成员已更改（重命名、参数列表更改等），DocMounter 会自动更新项目以插入更新的成员。所有过时的成员都不会被删除，并且可以使用特殊的搜索命令轻松找到。这允许您将描述从过时的成员复制到新的成员，并在不再需要时手动从项目中删除过时的成员。

  9. 如果您已经使用标准的 Visual Studio 方法记录了您的程序集，DocMounter 允许您轻松切换到 DocMounter 继续在此工具中进行工作。您可以从程序集的伴随 XML 注释文件或甚至直接存储在程序集中的描述属性中导入所有成员描述！

  10. 尽管 DocMounter 基于外部 Sandcastle 帮助编译器，并使用微软标准的 XML 文档和 Sandcastle MAML 语言来构建帮助主题，但它增加了一些很酷的附加功能，这些功能是您以前无法获得的。其中包括将图片插入成员主题以及在成员主题和概念主题之间创建交叉引用链接的能力。

最后，DocMounter 完全免费，您也可以免费获得其完整的源代码！

DocMounter 二进制文件和源代码

本文包含两个软件包的链接。

第一个是 DocMounter 的二进制文件。如果您只需要该工具，请使用此软件包。DocMounter 需要 .NET Framework 4.0，并作为便携式应用程序分发。它还需要 Sandcastle 和 VS SDK 中的一些外部工具，以及有关如何获取和安装这些工具的全面说明，请参阅产品随附的 DocMounter 手册。

第二个软件包是 DocMounter 的源代码。这是一个 VS 2010 解决方案，完全用 C# 编写。它可以用于检查工具的逻辑并根据您的需求进行修改。

© . All rights reserved.