C# 在使用 Sandcastle 构建期间自动生成 html 文档

Generate html documentation automatically during a build with Sandcastle

提问by Mark Ingram

What steps do I need to take to get HTML documentation automatically building via the build step in Visual Studio? I have all the comments in place and the comments.xml file being generated, and Sandcastle installed. I just need to know what to add to the post-build step in order to generate the docs.

我需要采取哪些步骤才能通过 Visual Studio 中的构建步骤自动构建 HTML 文档？我已经准备好了所有的评论和正在生成的 comments.xml 文件，并安装了 Sandcastle。我只需要知道在构建后步骤中添加什么即可生成文档。

采纳答案by Chev

Some changes have been made since this question was asked. Sandcastle no longer includes SandcastleBuilderConsole.exe. Instead it uses plain old MSBuild.exe.

自从提出这个问题以来，已经进行了一些更改。沙堡不再包括SandcastleBuilderConsole.exe. 相反，它使用普通的 old MSBuild.exe。

To integrate this with visual studio here is what I did:

为了将它与视觉工作室集成，我是这样做的：

Place this in your Post-build event:

把它放在你的构建后事件中：

IF "$(ConfigurationName)"=="Release" Goto Exit

"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"

:Exit

This will cause visual studio to build your documentation, only when you build in "Release" mode. That way you aren't waiting forever when you build in "Debug" mode during development.

这将导致 Visual Studio 构建您的文档，仅当您以“发布”模式构建时。这样，当您在开发过程中以“调试”模式构建时，您就不会永远等待。

A couple notes:

一些注意事项：

• My system is 64-bit, if yours is not then replace framework64with frameworkin the path to msbuild.exe.

• The way I have it setup is to document each project in my solution individually. If you have a "Sandcastle Help File Builder" project file which includes several projects together, then you probably want to get rid of ProjectName\and move docinto the solution directory. In this case you will want to only put the Post-build event commands on the project that is built LAST in your solution. If you put it in the Post-build event for every project then you will be rebuilding your documentation for each project that is built. Needless to say, you'll be sitting there a while. Personally I prefer to document each project individually, but that's just me.

• 我的系统是64位的，如果你没有再更换framework64用framework的路径msbuild.exe。

• 我设置它的方式是单独记录我的解决方案中的每个项目。如果您有一个包含多个项目的“Sandcastle 帮助文件生成器”项目文件，那么您可能想要删除ProjectName\并移至doc解决方案目录中。在这种情况下，您将只想将构建后事件命令放在解决方案中最后构建的项目上。如果您将它放在每个项目的 Post-build 事件中，那么您将为每个构建的项目重建文档。不用说，你会在那里坐一会儿。我个人更喜欢单独记录每个项目，但这只是我。

Installing Sandcastle and "Sandcastle Help File Builder".

安装 Sandcastle 和“Sandcastle 帮助文件生成器”。

If you don't know how to get Sandcastle and "Sandcastle Help File Builder" setup correctly, then follow these steps:

如果您不知道如何正确设置 Sandcastle 和“Sandcastle Help File Builder”，请按照以下步骤操作：

1. Download and install Sandcastle from http://sandcastle.codeplex.com/(if you have a 64 bit system, you will need to add an environment variable. The instructions are here.

2. Download and install "Sandcastle Help File Builder" from http://shfb.codeplex.com/(ignore warnings about MSHelp2 if you get any. You won't be needing it.)

3. Once you have those installed then use "Sandcastle Help File Builder" to create a new documentation project. When it asks you where to save the file, save it in the documentation folder you have in your solution/project. http://www.chevtek.com/Temp/NewProject.jpg

4. After creating a new project you'll need to choose which kind of documentation you want to create. A compiled windows help file, a website, or both. http://www.chevtek.com/Temp/DocumentationType.jpg

5. If you saved the SHFB project file in the directory where you want your documentation to be generated then you can skip this step. But if you want the generated documentation to be placed elsewhere then you need to adjust the output path. http://www.chevtek.com/Temp/OutputPath.jpgNOTE: One thing to keep in mind about the output path (which frustrated me for an hour) is that when you have website checked as the type of documentation you want, it will overwrite content in its output path. What they neglect to tell you is that SHFB purposely restricted certain folders from being included as part of the output path. Desktop is one such folder. Your output path cannot be on the desktop, not even a sub-folder of desktop. It can't by My Documents either, but it CAN be a subfolder of my documents. If you get errors when building your documentation, try changing the output path and see if that fixes it. See http://shfb.codeplex.com/discussions/226668?ProjectName=shfbfor details on this.

6. Finally, you will need to add a reference to the project you want to document. If you are doing individual projects like I do, then for each SHFB project file you create, you will reference the corresponding .CSPROJ file. If you have one SHFB project for your entire solution, then you would find the .SLN file for your solution. (sandcastle also works if you reference the compiled DLLs, but since you're integrating it with Visual Studio I find it makes more sense to reference the project/solution files instead. This may also mean that it really doesn't matter which project you do the post-build event on since it's referencing the code instead of the DLLs, but it's better to be safe and put it on the last project that's built) http://www.chevtek.com/Temp/AddSource.jpg

7. Save the project and you can close "Sandcastle Help File Builder". Now all is setup. Just be sure to put the documentation project file in the appropriate folder that the batch commands point to in the Post-build event.

1. 从http://sandcastle.codeplex.com/下载并安装 Sandcastle （如果您有 64 位系统，则需要添加一个环境变量。说明在这里。

2. 从http://shfb.codeplex.com/下载并安装“Sandcastle 帮助文件生成器” （如果有任何警告，请忽略有关 MSHelp2 的警告。您将不需要它。）

3. 一旦你安装了这些，然后使用“Sandcastle Help File Builder”来创建一个新的文档项目。当它询问您保存文件的位置时，请将其保存在您的解决方案/项目中的文档文件夹中。 http://www.chevtek.com/Temp/NewProject.jpg

4. 创建新项目后，您需要选择要创建的文档类型。已编译的 Windows 帮助文件、网站或两者。 http://www.chevtek.com/Temp/DocumentationType.jpg

5. 如果将 SHFB 项目文件保存在要生成文档的目录中，则可以跳过此步骤。但是如果您希望将生成的文档放在其他地方，那么您需要调整输出路径。 http://www.chevtek.com/Temp/OutputPath.jpg注意：关于输出路径（这让我沮丧了一个小时）要记住的一件事是，当您将网站检查为所需的文档类型时，它将覆盖其输出路径中的内容。他们没有告诉您的是，SHFB 故意限制某些文件夹作为输出路径的一部分包含在内。桌面就是这样一个文件夹。您的输出路径不能在桌面上，甚至不能在桌面的子文件夹中。它也不能通过我的文档，但它可以是我的文档的子文件夹。如果您在构建文档时遇到错误，请尝试更改输出路径并查看是否可以解决问题。有关详细信息，请参阅http://shfb.codeplex.com/discussions/226668?ProjectName=shfb。

6. 最后，您需要添加对要记录的项目的引用。如果您像我一样在做单独的项目，那么对于您创建的每个 SHFB 项目文件，您将引用相应的 .CSPROJ 文件。如果您的整个解决方案有一个 SHFB 项目，那么您会找到解决方案的 .SLN 文件。（如果您引用已编译的 DLL，sandcastle 也可以使用，但是由于您将它与 Visual Studio 集成，我发现引用项目/解决方案文件更有意义。这也可能意味着您选择哪个项目并不重要执行构建后事件，因为它引用代码而不是 DLL，但最好是安全的并将其放在构建的最后一个项目中） http://www.chevtek.com/Temp/AddSource.jpg

7. 保存项目，您可以关闭“Sandcastle Help File Builder”。现在一切都设置好了。只要确保将文档项目文件放在批处理命令指向的 Post-build 事件中的适当文件夹中。

I hope my short tutorial helps you out! It was very hard for me to find any decent tutorials showing me how to use sandcastle, let alone how to integrate it with visual studio. Hopefully future google searches will turn up this question.

我希望我的简短教程可以帮助您！我很难找到任何像样的教程来向我展示如何使用 Sandcastle，更不用说如何将它与 Visual Studio 集成了。希望未来的谷歌搜索会出现这个问题。

回答by Joe

I recommend you install Sandcastle Help File Builder from Codeplex.

我建议您从Codeplex安装 Sandcastle Help File Builder 。

You can run this from the command line, e.g. from a Post-Build event. The simplest command line is:

您可以从命令行运行它，例如从 Post-Build 事件。最简单的命令行是：

<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle is very slow, so I only run it for Release Builds. To do this, create a Post-Build event with a command something like the following, which passes the configuration name to a batch file:

Sandcastle 非常慢，所以我只为发布版本运行它。为此，请使用类似于以下内容的命令创建构建后事件，该命令将配置名称传递到批处理文件：

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)

Then inside the batch file you can test if the first argument is "Release" and if so run SandcastleBuilderConsole.exe.

然后在批处理文件中，您可以测试第一个参数是否为“Release”，如果是，则运行 SandcastleBuilderConsole.exe。

回答by Marc Gravell

I must admit that I find the current version of Sandcastle a bit lacking; for large projects it is quite slow, and it isn't easy to integrate (since it is still early).

我必须承认，我发现当前版本的 Sandcastle 有点欠缺；对于大型项目，它很慢，并且不容易集成（因为还为时过早）。

For regular use, I actually find it easier just to point reflector at a folder with the dll and xml files - IIRC, it will load the xml file(s) as you navigate around.

对于常规使用，我实际上发现将反射器指向包含 dll 和 xml 文件的文件夹更容易 - IIRC，它会在您浏览时加载 xml 文件。

Plus I almost always have reflector open anyway...

另外，无论如何我几乎总是打开反射器......

[edit] checked, and yes - xml comments show in the disassembler panel

[编辑] 选中，是的 - 反汇编面板中显示 xml 注释

回答by Martin Kool

Install these:

安装这些：

NDoc: http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi?download

NDoc：http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi? download

HTML Help Workshop: http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

HTML 帮助研讨会：http: //www.microsoft.com/downloads/details.aspx?FamilyID =00535334-c8a6-452f-9aa0-d597d16580cc&displaylang= en

Then use the NDocConsole.exe command line to generate documentation in either MSDN or CHM form:

然后使用 NDocConsole.exe 命令行以 MSDN 或 CHM 形式生成文档：

@c:\progra~1\NDoc\NDocConsole.exe MyCode.dll,MyCode.xml -Documenter=MSDN-CHM

@c:\progra~1\NDoc\NDocConsole.exe MyCode.dll,MyCode.xml -Documenter=MSDN-CHM

I myself have made an External Tool for this and gave it a shortcut, but as the previous poster said you can hook it up to a postbuild event and there you go.

我自己为此制作了一个外部工具并给了它一个快捷方式，但正如之前的海报所说，您可以将其连接到构建后事件，然后就可以了。

(PS I have been using the setup above for a few years now and am very happy with it)

（PS 我已经使用上面的设置几年了，对它非常满意）

回答by Oliver Nina

An easy way to do this as suggested above is using Sandcastle Help File Builder. There have been some changes made to the build process from the command line and now these projects can be built with MSbuild instead of SandcastleBuilderConsole.exe. So all you have to do is:

上面建议的一种简单方法是使用 Sandcastle 帮助文件生成器。从命令行对构建过程进行了一些更改，现在可以使用 MSbuild 而不是 SandcastleBuilderConsole.exe 来构建这些项目。所以你所要做的就是：

MSbuild.exe ProjectName.shfb

MSbuild.exe 项目名称.shfb