如何找出导致生成的 Sandcastle 文档存在差异的原因？

Posted 2023-02-23

【中文标题】如何找出导致生成的 Sandcastle 文档存在差异的原因？

【英文标题】：How can I find out what's causing differences in generated Sandcastle docs?

【发布时间】：2013-02-01 13:55:40

【问题描述】：

在 Noda Time 中，我们使用 Sandcastle 和 SHFB 生成文档。然后，我们将文档提交回源存储库 - 主要是因为这样可以轻松查看最新（和历史）文档。

我是该项目的主要开发人员，但我使用两台计算机 - 不幸的是，目前他们正在构建不同的文档，即使它们都更新到相同的源。

两台计算机在我能想到的所有重要方面都相同：

沙堡 2.7.2.0 SHFB 1.9.6.0 VS 2012 Professional（均在“程序”中报告版本 11.0.50727.1，均在“关于”页面中报告“版本 11.0.51106.01 更新 1”） .NET Framework 4.5 本地帮助内容的最新版本（其他框架版本没有本地帮助内容）

为确保构建干净而采取的步骤：

已删除 SHFB 缓存文件夹 (C:\Users\Jon\AppData\Local\EWSoftware\Sandcastle Help File Builder\Cache) 删除了生成文档的文件夹 删除了SHFB工程文件相关的用户设置文件 删除了 Visual Studio 中的符号缓存

仍然存在差异。它们似乎仅限于从 MSDN 本身继承的文档，尤其是 Object.Finalize。

版本 1（在机器“Chubby”上生成）：

<div class="summary">Allows an object to try to free resources and perform
other cleanup operations before it is reclaimed by garbage collection.</div>

版本 2（在机器“Sandy”上生成）：

<div class="summary">Allows an <a 
   href="http://msdn2.microsoft.com/en-us/library/e5kfa45b" target="_blank">
   Object</a> to attempt to free resources and perform other cleanup operations
   before the <a href="http://msdn2.microsoft.com/en-us/library/e5kfa45b" 
   target="_blank">Object</a> is reclaimed by garbage collection.</div>

两者都链接到同一个 MSDN 文档，看起来像第 1 版（没有指向 Object 的链接）。

查看一些更改的文件，更改是一致的并且仅限于该成员。

Sandcastle 可能从哪里获得此文档，我怎样才能让两台计算机的行为方式相同？

编辑：另外一个信息片段 - 在两台机器上清理缓存并重建文档后，SHFB 缓存目录中有三个文件：

Reflection.cache 在两台机器上的大小相同 MsdnUrl.cache 在两台机器上的大小相同 .NETFramework_4.0.0319_E8879A28.cache 在 Chubby 上的大小为 13,377,733 字节，在 Sandy 上为 13,337,949 字节

编辑：重大进展！我发现差异可能来自哪里......

文件c:\Windows\Microsoft.NET\Framework\v2.0.50727\en\mscorlib.xml：

在 Chubby 上是 8,005,263 字节，日期为 2011 年 12 月 12 日，并且有 Finalize 的非链接文本 在 Sandy 上是 9,740,370 字节，日期为 2009 年 8 月 31 日，包含 Finalize 的文本，其中包括链接

在两台机器上，mscorlib.dll 本身的大小相同（4,550,656 字节），修改日期为 2012 年 9 月 13 日。

但是我怎样才能让它们相同呢？这种差异从何而来？ （服务包？）

编辑：好的，c:\Windows 中的版本是一个红鲱鱼 - 这是 c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework 中的版本，这是罪魁祸首。我将看看我是否可以找出为什么安装之间可能会有所不同...

【问题讨论】：

您确定您的 SC 可执行文件路径中没有其他版本？嗯，也许有一个可用于 Windows 的 Unix“which”命令。

@larsw: 每台机器上只有一个 SandcastleHelpFileBuilder.targets 文件:(

差异可能是由于在一台机器上安装了任何 Windows 系统 /.NET 更新/补丁，但不是在另一台机器上？您是否以相同的方式在两台机器上安装了所有现有的 .NET 框架版本？

@stakx：两台机器都是“最近”（2012 年末）安装的，并且都完全是最新的 Windows 更新......但这当然不是一回事......

@larsw 您可以在 Windows cmd-line 中使用 where 来查找（默认情况下）位于 PATH 环境变量的可执行文件。

【参考方案1】：

考虑到您最近的编辑的一些想法，虽然我同意这有点在黑暗中拍摄......

我会使用“Beyond Compare”之类的工具来比较两台机器上的 .Net Framework 文件和 XML 文件（“文件夹比较”配置文件）。 支持二进制级别比较以完全确定...如果您的两台机器都是本地的，它应该非常快。

您也可以尝试在两台机器上运行 Mark Russinovich 的进程监视器 (http://live.sysinternals.com/procmon.exe) 并运行文档构建过程。 这样，您将看到哪些文件正在被读取并参与帮助文件构建过程，以及它们来自哪里...... 您将获得大量输出，因为它将显示系统中发生的所有事情；您可能希望禁用注册表和网络监控，只保留文件监控，并排除与文档构建过程无关的任何过程。

我不是帮助生成专家，但我认为文本来自 XML 文件，因此您可能还想设置一个过滤器，只显示 xml 文件。

如果您可以识别所涉及的文件，那么您可能只需将它们从一台机器复制到另一台机器。

【讨论】：

我现在找到了涉及的文件——它肯定是参考程序集。我通过删除继承的文档得到了临时修复，但我也想知道为什么存在这些差异。

你有不同程序集的版本号吗？如果您使用 google site:support.microsoft.com 查找版本号，您是否找到任何提及它们的 KB？一种可能是在 Windows 更新周期之外发布的修补程序会以某种方式登陆您的一台计算机（例如，另一个应用程序已安装该修补程序作为先决条件）？

抱歉，没有 - 参考程序集目录中的 XML 文件。我让微软的一些人调查可能发生的事情（为什么有两个不同的版本）。