SHFB的IntelliSenseComponent的输出文件夹有哪些规则适用？

Question

Noda Time存在一个问题，它发布的XML文档文件包含所有的内部和私有成员，这很遗憾。

幸运的是，Sandcastle Help File Builder有一个自定义构建组件-IntelliSenseComponent - 可以完全解决这个问题...理论上。不幸的是，我无法弄清楚如何正确配置它。

文档提供了以下示例：

 <output includeNamespaces="false" namespacesFile="Namespaces"
   folder="{@OutputFolder}" />

上述内容取自Sandcastle Help File Builder的配置文件，其中使用了替换标签{@SHFBFolder}和{@OutputFolder}来在文件路径中插入帮助文件生成器的文件夹以及项目输出文件夹。在构建时，这些标签会被适当的值所替换。如果在您自己的构建脚本中使用该组件，请将这些标签分别替换为组件程序集和输出文件夹的相对或绝对路径。

好的，我正在使用SHFB，所以我期望这将起作用。但是，除了绝对路径外，我什么都试过了，但都无法生效。

folder="."
folder="{@OutputFolder}"
folder="{@OutputFolder}XYZZY"
folder="{@OutputFolder}\XYZZY"
folder="{@OutputFolder}/XYZZY"
folder="{@OutputFolder}/XYZZY/"

（我只是使用XYZZY作为一个容易搜索的东西。）

查看源代码，我希望我可以使用环境变量，但这并不起作用：

folder="%CD%\XYZZY"

虽然这样做可以解决问题，但是它确实不推荐使用，因为它会绕过类型检查。

folder="%USERPROFILE%\XYZZY"

这个代码可行：

folder="c:\users\jon\test\xyzzy"

...但我真的不想在那里使用绝对路径名。

文档建议这应该非常容易...我错过了什么？

涉及的版本：

• SHFB：1.9.3.0
• Sandcastle：2.6.10621.1

- Jon Skeet

---

folder="%CD%\XYZZY"不起作用，因为Environment.ExpandEnvironmentVariables不会扩展%CD%，而IntelliSenseComponent使用它。我相信只有cmd.exe可以扩展它（就像%TIME%，%CMDCMDLINE%等）。 - Igor Korkhov

Answer 1

我的实验表明SHFB的IntelliSenseComponent确实正确处理了{@OutputFolder}，但有一个微妙之处。

如果在指定folder属性时

<output includeNamespaces="false" namespacesFile="Namespaces"
        folder="..." />

指向项目OutputPath文件夹内的一个文件夹（在您的情况下为.\docs\api），然后SHFB的构建过程会创建该文件夹，但在生成网站内容之前会将其删除：

Last step completed in 00:00:34.5875
-------------------------------
Combining conceptual and API intermediate TOC files...

Clearing any prior web output
    Last step completed in 00:00:00.2360
-------------------------------
Extracting HTML info for HTML Help 1 and/or website...

问题在于{@OutputFolder}的默认值与$(OutputPath)的值完全相同，因此，如果您在folder属性中放置类似于{@OutputFolder}\foo这样的内容，则在构建完成后您将永远看不到foo。

解决方案很简单：指定位于项目输出文件夹外部的文件夹，如下所示：

<output includeNamespaces="false" namespacesFile="Namespaces"
        folder="{@OutputFolder}\..\distilledApi" />
<!--                            ^^       -->

希望这可以帮到你。

- Igor Korkhov