Sandcastle Help File Builder（.NET帮助文档工具）的版本选择心得——支持VS2010至VS2015，高版本项目文件问题

作者： zyl910

一、缘由

“Sandcastle Help File Builder”（简称SHFB）是一个很好用.NET 帮助文档生成工具。
但它的每个版本支持的VS版本范围有限，且官网没有明确说明它与VS版本的区别。导致经常出现“明明装了SHFB，但VS打开不了它的项目”问题。
这时只有逐个版本安装尝试了。而GitHub下载速度慢，导致要花很久时间才能找到合适的版本。于是我做了一次完整的实验，有了一些心得。

二、心得

2.1 尝试安装2个版本

最初曾经试过安装2个版本的办法——

1. “先安装旧版本SHFB，再安装新版本SHFB”的办法无效。系统中只能存在一个SHFB版本，安装新版本后，旧版本会被覆盖掉。导致还是仅支持新版本的VS范围。
2. “先安装旧版本SHFB，再安装新版本的vsix”的办法无效。低版本VS编译正常，高版本VS虽然能打开SHFB项目，但无法编译，提示需要升级SHFB。
3. “先安装新版本SHFB，再安装旧版本的vsix”的办法无效。高版本VS编译正常，低版本VS虽然能打开SHFB项目，但无法编译，提示.NET版本问题等错误。
4. “先安装旧版本SHFB，先安装新版本SHFB，再安装旧版本的vsix”的办法无效。高版本VS编译正常，低版本VS虽然能打开SHFB项目，但无法编译，提示.NET版本问题等错误。

该思路不行。看来只能挑一个版本了。

2.2 版本选择

逐个安装测试了SHFB对VS的支持范围——

• SHFBGuidedInstaller_2015.01.12.0: 支持VS2010~VS2013 及 VS2015预览版。shfb.codeplex.com的最后版本。
• SHFBInstaller_v2015.5.2.0: 支持VS2010~VS2015。【注意】该版本是支持VS2010的最后一个版本。
• SHFBInstaller_v2015.7.25.0: 支持VS2013~VS2015。【注意】该版本不再支持VS2010、VS2012。
• SHFBInstaller_v2016.4.9.0: 支持VS2013~VS2015。
• SHFBInstaller_v2016.5.28.0: 支持VS2013~VS2015 及 VS2017预览版。
• SHFBInstaller_v2016.9.17.0: 支持VS2013~VS2015 及 VS2017预览版。
• SHFBInstaller_v20171.28.0: 支持VS2015 及 VS2017预览版。【注意】该版本是支持VS2013的最后一个版本。
• SHFBInstaller_v2017.5.15.0: 支持VS2015 及 VS2017（但实测发现其对VS2017支持还有很多问题）。【注意】该版本不再支持VS2013。

目前主要是 VS2010、VS2015这2个版本的使用率较高，故应选择“SHFBInstaller_v2015.5.2.0”。

2.3 打开SHFB高版本项目文件问题

上一节说我们选定了“SHFBInstaller_v2015.5.2.0”这个版本。但当遇到高版本的SHFB项目文件时，该怎么办呢？

首先，尝试安装2个版本的办法是行不通的，详见“2.1 尝试安装2个版本”。

办法是——

• 用文本编辑器打开shfbproj文件，将SHFBSchemaVersion的值改为“1.9.9.0”（例如将 <SHFBSchemaVersion>2015.6.5.0</SHFBSchemaVersion> 改为 <SHFBSchemaVersion>1.9.9.0</SHFBSchemaVersion> ）。

修改了版本之后，一般就能用“SHFBInstaller_v2015.5.2.0”正常处理了。

参考文献

• http://shfb.codeplex.com/
• https://github.com/EWSoftware/SHFB
• ASP.NET 魔法學院（jeff377）《使用 Sandcastle Help File Builder 制作 VS.NET 的 HELP 文件》. http://www.cnblogs.com/jeff377/archive/2008/11/15/1334233.html

SHFBInstaller_v2015.5.2.0.zip
http://pan.baidu.com/s/1sltz2PZ