使用Sandcastle Help File Builder生成的CHM中HTML页面不显示问题

AI 小北

2026-7-9

在新版Sandcastle Help File Builder中无法将WhatsNew.html加入CHM目录的排查方案

问题描述

我在旧版Sandcastle Help File Builder（SHFB 1.9.3.0）中，通过在.shbproj文件添加以下配置，能成功将WhatsNew.html页面加入CHM的目录中：

<ItemGroup>
    <Content Include="WhatsNew.html" />
</ItemGroup>

但升级到最新版SHFB后，使用如下构建设置时：

<HelpFileFormat>HtmlHelp1</HelpFileFormat>
<SyntaxFilters>Standard</SyntaxFilters>
<PresentationStyle>VS2013</PresentationStyle>
<CleanIntermediates>True</CleanIntermediates>
<KeepLogFile>True</KeepLogFile>
<DisableCodeBlockComponent>False</DisableCodeBlockComponent>

该HTML页面不再显示在生成的CHM文件中，且构建过程无任何错误或警告，请问可能遗漏了哪些配置？

可能的解决配置

替换为新版支持的AdditionalContent项
新版SHFB已不再使用Content项识别自定义帮助页面，需改用AdditionalContent：
```
<ItemGroup>
    <AdditionalContent Include="WhatsNew.html" />
</ItemGroup>
```

添加元数据指定页面展示规则
若仅添加AdditionalContent仍不生效，需补充元数据定义页面的显示名称和目录位置：

<ItemGroup>
    <AdditionalContent Include="WhatsNew.html">
        <Title>更新日志</Title>
        <Placement>Root</Placement>
    </AdditionalContent>
</ItemGroup>

检查路径与文件属性
确认WhatsNew.html的路径相对于项目文件无错误，同时将文件的复制到输出目录属性设置为"始终复制"或"如果较新则复制"，避免构建时未将文件同步到输出目录。
排查PresentationStyle兼容性
VS2013样式可能对自定义页面的处理逻辑有调整，可临时切换到其他样式（如VS2010）测试，确认是否是样式本身的限制导致页面不显示。