发布日期：2024-11-03 13:01 点击次数：89
原文地址：-html-documentation-for-y.html#comments萝莉 操
Sandcastle 功能概述
要是您使用过的表率集中，带有翔实的 API 说明文档，况兼文档的阵势和 MSDN 上的一样，您将发现这么 API 说明文档的是何等的肤浅。生成雷同的 HTML 阵势文档的方法有好多，不外，我发现其中最大约的方法是使用 Sandcastle 用具来生成这么的 API 文档。Sandcastle 是微软开采的一款开源的文档生成器，它不错读取您的表率集（DLL 和 EXE 文献）和 XML 凝视文献，而且能自动生成相应的 HTML 阵势的文档。Sandcastle 既是一款绝顶生动的用具，同期它亦然一款绝顶复杂的用具。不外运道的是，还有另外一款与之雷同的援助用具， Sandcastle Help File Builder，这个用具让您在几分钟之内就不错很容易地获得和运行 Sandcastle。
本教程将带您创建大约的 HTML 阵势的类描绘文档，底下是咱们接下来要作念的：
门径一: 装配 Sandcastle 和 Sandcastle Help File Builder 门径二: 创建一个称呼为 Guy.cs 的 C# 代码文献 门径三: 把 C# 代码编译成 Guy.dll 表率集 门径四: 装配 Sandcastle Help File Builder 花式 门径五: 运行 Sandcastle备注，咱们还需完成一些畸形的事情：
5.1 缔造复 Sandcastle [丢失 <summary> 节点]的问题 5.2 添加一个 AssemblyInfo.cs 文献来缔造表率集属性 5.3 愚弄 MSBuild 从结尾台高唱行来运行 Sandcastle 的花式文献 5.4 在 Visual Studio 花式中愚弄 Sandcastle Help File Builder 花式门径一: 装配 Sandcastle 和 Sandcastle Help File Builder
Sandcastle 是一款绝顶宏大、生动的用具。由于它是基于结尾台高唱行的，因此莫得相应的图形界面末端可供使用。这么您就很难松开启动并使用它就。和其他大部分软件一样，Sandcastle 也得志 80/20 门径 : 80% 的用户只是使用其中 20% 的功能。运道的是，当今有一个称呼为 Sandcastle Help File Builder 的用具，它让您绝顶肤浅地使用 20% 的功能。有了 Sandcastle 和 Sandcastle Help File Builder (巧合把它简称为缩写阵势 SHFB)，您几分钟内就不错启动并生成援助文献和 HTML 文档了。
领先下载和装配 Sandcastle and Sandcastle Help File Builder（这里我用的是 2015.1.12.0版块）：
使用下载采集 Sandcastle CodePlex 页面 来下载和运行最新的安谧版的装配表率 对 Sandcastle Help File Builder 作念调换的操作 确保您综合到了 Sandcastle 和 Sandcastle Help File Builder 的装配目次。这里将它们被装配在以下旅途 D:\Program Files 或者 D:\Program Files(x86)— Sandcastle 被装配在称呼为 Sandcastle 文献夹下，SHFB 被装配在 EWSoftware\Sandcastle Help File Builder 文献旅途下。综合，装配 Sandcastle 和 Sandcastle Help File Builder 后，您还不错把它们装配目次底下的实质全部复制到另外一个目次下，从而把它们的装配旅途改成你思要的旅途，在新目次下，它们依然不错被启动并使用。要是您使命的机器被锁住，您弗成用它来装配表率 — 为了安全，办公室里的好多电脑皆会被锁住 — 这个功能将很有效。当您在一个构建做事器上运行一个一语气的生成高唱，来生成 HTML 文档，但是您又莫得经管员权限时，它也不错派上用场。
门径二: 创建一个称呼为 Guy.cs 的 C# 代码文献
Sandcastle 按两步来生成文档。 第一步，利用反射来查验表率集中的宇宙类中的成员，第二步，读取 XML 凝视文档并生成的关联纪录。
当 Sandcastle 从表率集中创建文档时，它需要表率集中至少有一个定名空间和况兼定名空间中至少包含一个宇宙的类。不然，它将抛出一个无理（咱们将在几分钟内看到）。因此，咱们需要作念的第一件事是准备好您的代码，并添加 XML 凝视。
（要是您之前莫得使用过 XML 凝视，您不错在我的 C# XML 注佛教程 中快速的浏览它们。相似，要是您对 .NET 表率集和 C# 定名空间比拟诱导，浏览一下我的 C# 与 .NET 表率集和定名空间教程 。）
在本教程的第一部分, 咱们将在结尾台高唱教导行中完成扫数后台任务。是以当今，您应该使用 Notepad 来编码咱们创建的源文献。在高唱行中实践扫数后台高唱和在 Visual Studio 实践时的后果一样。我比拟惦记结尾台高唱行，因为这里使用的是手动构建用具，扫数咱们需要知谈怎样创建文献。而且在构建经过中，还需要在结尾台高唱窗口中使用一些结尾台高唱，然则许多 .NET 开采东谈主员使用结尾台高唱教导符的技术并不长。要是您莫得使用过，也无须惦记，您只需望望网上的这个章节 从高唱教导符中编译和运行 C# 代码。
我照旧准备了一个带有 XML 凝视的类。它在我的 我的大约用具类 Guy。前去并 从该采集中复制 Guy.cs 的代码 ，把它粘贴到 Notepad,，终末将其保存文称呼为 Guy.cs 的文献。
底下是 Guy 类的代码：
综合 Guy 类是怎样利用 String 类和 Console 类的？它们皆是 System 定名空间下的一部分，因此为了幸免编译出错，需要 在 Guy.cs 文献的顶部添加这一瞥:
您的代码当今不错准备去编译了。（您可能照旧发现了一个小小的无理，这个无理将使 Sandcastle 出现问题 — 咱们将在几分钟内缔造它）
门径三: 把 C# 代码编译成 Guy.dll 表率集
当今咱们运转使用 C# 编译器的结尾台高唱 CSC 高唱来编译代码。底下先容何如来实践它：
要是你得到一个 "系统找不到指定的旅途 " 的无理, 在高唱行顶用 v3.5 替换 v4.0.30319 . 本教程中的一切表率皆是在 .NET 3.5 下运行的。 v4.0.30319 暗意 .Net Framework 4.0 的版块号。本教程中扫数的使命皆不错在 .NET 3.5 中得胜运行，是以要是你照旧装配了它，你不错把 v4.0.30319 替换成 v3.5后再运行。 或者，要是你照旧装配了 Visual Studio ，你不错启动 Visual Studio 的结尾台高唱，csc.exe 定名就在对应的目次下。（Express 版块的 Visual Studio莫得此功能）
掀开高唱行教导符并把目次指向你保存 Guy.cs 文献的处所，运行底下的高唱：
结尾台将涌现的以下界面 （我的 Guy.cs 文献保存在 F:\temp\Guy）：
当你运行 csc.exe，它会新建两个文献： Guy.dll （包含 Guy 类的表率集）和 Guy.xml （包含从 XML 凝视中生成的文档）。
门径四: 缔造 Sandcastle Help File Builder 花式
为了运行 Sandcastle Help File Builder，你只需要缔造几个变量然后运行 SandcasteBuilder 的图形界面。最大约的方法便是复制底下三个高唱到结尾台高唱行：
（您不错按以下容貌在结尾台窗口中使用粘贴功能：点击窗口左上角的菜单图标，并聘用裁剪 >> 粘贴）
掀开 Sandcastle Help File Builder 的操作界面，在菜单中聘用文献 >> 新建花式，并定名为 Guy.shfbproj （这是 SHFB 花式通用的扩张名）。底下是新建 SHFB 时的操作界面：
接下来，你需要告诉 SHFB 从那处去找 DLL and XML 文献，来给 Sandcastle 使用并生成关联文档。先在花式贵府经管器中，右击“文档”，聘用 "添加文档源..."， 导航到 Guy.dll 文献并选中它，SHFB 会自动一并添加 XML 文献 — 需要把 Guy.dll 和 Guy.xml 皆添加到文档源中：
要是您正在使用的 dll 文献中包含对其他 dll 文献的援用萝莉 操，您不错通过资源经管器中的援用节点来添加对它们的援用。就像在 Visual Studio 中添加援用一样来添加对它们的援用。
接下来，您将聘用输出阵势。默许地，Sandcastle 会生成一个 HTML 援助文档 CHM。 在 Build 选项卡下找到 Help File Formats 下拉框，去除 HtmlHelp1 的选中，然后勾选 Website：
您也不错使用 HtmlHelp1 选项来生成一个 HTML 匡助（*.chm后缀）文献。但是在您使用之前，您需要装配 Html Help 1.x SDK。查阅 HTML Help MSDN page 不错获得更多的信息和下载采集。
点击用具栏上的 “保存扫数” 按钮来保存 Guy.shfbproj 花式。当今，您的 Sandcastle Help File Builder 花式就准备好了。
门径五: 运行 Sandcastle
底下将运行 Sandcastle。在其菜单中聘用 >> 生成文档 来运行 Sandcastle。在生成输出标签中，您会看到 Sandcastle 的运功绩态：
噢，您好像得到了一个无理！
记着我之前何如说的，您的表率集必须至少包含一个定名空间和一个宇宙类。而表率集 Guy.dll 皆莫得包含。
运道的是，这很容易修改。在 Notepad 中掀开 Guy.cs 并作念如下改变 。您将使用 namespace 要津字来把类 Guy 存放到称呼为 GuyTest 的定名空间中，同期您将使用 public要津字来使类 Guy 酿成宇宙造访类 — 保证您在类界说末尾处添加了一个关闭的花括号！底下是界说好的类和定名空间（新添加的文本用 粗体 暗意）
既然 Guy 类照旧是宇宙的并在 GuyTest 定名空间中，您就不错编译表率集了。再次运行 CSC 高唱来重壮盛成 Guy.dll 表率集。 此次应该重写 Guy.dll 表率集和 Guy.xml 文献。
此次 CSC 定名会给出一个缺失 XML 凝视的训诫，但也会运行：
咱们将在几分钟内缔造这个问题。但是领先 使用文档 >> 生成花式并再次运行 Sandcastle。 此次生成将会绝顶得胜：
祝愿您 — 当今您照旧得胜生成了 HTML API 文档！在IE浏览器中掀开匡助文档 Help\index.html。 在页面的尖端，您会得到一个训诫信息：
点击它并从菜单中聘用“允许抑止的实质...”，这么作念后，您将会看到壮盛成的 HTML 匡助文档！
5.1 缔造 Sandcastle [丢失 <summary> 节点]的问题
您可能照旧综合到生成的 HTML 匡助页面中，有一个这么的标题： A Sandcastle Documented Class Library 。不错修改这个标题，复返到花式属性页并修改匡助标题属性。 确保终末您保存了 SHFB project file 文献。
接下来，您还记起实践 CSC 高唱时，涌现的缺失 XML 凝视的训诫吗？
在 IE 浏览器中找到 HTML 匡助，并导航到 GuyTest 定名空间 >> Guy 类 >> Guy 方法 >> ToString 方法。您将看到这个：
这是 Sandcastle 生成的教导信息，因为它找不到关联的凝视。您不错通过为 ToString() 方法添加一个 XML 凝视来缔造这个问题。为上头的 ToString() 方法，添加这么的凝视：
5.2 添加一个 AssemblyInfo.cs 文献来缔造表率集属性
终末，点击 Guy 类的浪漫一个成员，您将看到底下这行说明：
Assembly: Guy (in Guy.dll) Version: 0.0.0.0
您不错创建一个 AssemblyInfo 文献来改变版块号。它和 Visual Studio 生成的典型的属性文献一样。底下是 Guy 类的一个属性文献的例子 — 我用 Visual Studio 先新建一个新花式然其后创建它，但是您只可 把它粘贴到 Notepad 并保存为 AssemblyInfo.cs 文献：
AssemblyInfo.cs:
当今您不错 使用 CSC 高唱重新编译表率，此次添加 AssemblyInfo.cs 到高唱行的末尾。 底下是结尾台高唱行代码：
在您的文献资源经管器中右击 Guy.dll 并聘用 Properties，点击“翔实信息”标签，您将看到新的版块号，标题，公司和版权。
回到生成的 HTML 匡助页面，在左边的文献树节点里点击（“GuyTest Namespace”）节点。综合：它又产生了一个相似的无理：
[缺失 "N:GuyTest" 文档]
XML 凝视在定名空间中无效，请不要笃信我之前说过的话 — 尝试在定名空间上添加一个 <summary> 凝视并重新编译您的代码。不然您将得到底下的训诫：
训诫 CS1587: XML 凝视莫得被遗弃在一个正确的讲话元素下
您的 DLL 和 XML 文献将像以往一样被生成，但是 XML 文献将不会对定名空间的进行凝视。
运道的是，这钟事情在 Sandcastle 中很容易处理。回到花式“属性”页并在凝视部分点击 "Summaries" 选项。点击“Edit Namespace Summaries”按钮，将弹出定名空间凝视窗口。在窗口中的 "Checked namespaces" 选项盒中，点击 GuyTest 定名空间来选中它，并确保它被选中，同期也选中它的上头是"（global）"选项。然后确保右边的"Selected namespace appears in"窗口中的 Guy 被选中。然后鄙人面的大的文本框中输入一个凝视。
关闭定名空间选录窗体。当今定名空间选录属性将读取：1 涌现选录，0 从花式中摈弃。
点击用具栏上的全部保存按钮并重壮盛成文档。当您在 IE 浏览器中重新加载它时，您将看到定名空间和 ToString() 方法的选录。
5.3 愚弄 MSBuild 从结尾台高唱行来运行 Sandcastle 的花式文献 当您的 SHFB（*.shfbproj） 花式文献不错泛泛运行后，您还不错在结尾台高唱行中使用 MSBuild 定名来生成它。 这是用于 Visual Studio 的代码生成器。和用来编译 C# 的 CSC 高唱 一样，它和 .NET Framework 沿途被装配。同期您需要运行底下的高唱来生成 Guy 类的说明文档：
等等 — 您得到底下的无理了吗？
无理 MSB4019: 未找到导入的花式 "C:\SandcastleHelpFileBuilder.targets"。请确保声名的旅途正确，况兼该文献在磁盘上存在。
要是您得到了这个无理，确保 DXROOT, SHFBROOT, 和 LANGUAGE 变量皆被缔造好了。要是您不缔造 SHFBROOT 变量，您将得到这么的信息。相似要是您不缔造 DXROOT 变量 SHFB 将找不到 Sandcastle。因此，要是这些环境变量莫得被缔造时，您可能需要去 再次实践这三个缔造结尾台的定名 （在运行 SHFB 之前您照旧实践过的调换的高唱）。
底下是我运行后的界面：
用 MSBuild 高唱生成的文档和上头用 CSC 高唱生成的文档豪阔一样。要是您需要把文档整合到一个执续生成的环境中，MSBuild 高唱将绝顶有效。
是否得到一个训诫 (SHFB : 训诫 BHT0001)? 要是您得到了，这个问题已在一些 SHFB 版块中被发现。您不错使用 MSBuild 3.5 高唱来抑止这个训诫 而不是 4.0.x。在大无数情况下，SHFB 和 Sandcastle 仍然不错很好地生成文档，即时产出了这个训诫。获得更多信息，请检察 SHFB Codeplex 站点上的这个线程。
5.4 在 Visual Studio 花式中愚弄 Sandcastle Help File Builder花式
Sandcastle Help File 生成器也不错使用 C# 花式文献（*.csproj）动作一个文档源。底下将先容怎样获得您的 Guy.cs 文献和 AssemblyInfo.cs 文献，并把它们添加到 Visual Studio 的一个类库中，然后从这个花式中，利用 Sandcastle Help File Builder 来生成文档。
领先，创建一个新的 Visual Studio 花式并添加 Guy.cs 和 AssemblyInfo.cs 文献：
启动 Visual Studio 并 创建一个新的称呼为 GuyTest 的类库 （GuyTest.csproj） 删除 Visual Studio 自动为您添加的 Class1.cs文献 在资源经管器中右击 GuyTest 并添加一个已存在的花式到您的工程中。导航到 Guy.cs 文献并添加它 在资源经管器中伸开“属性”文献夹并删除 AssemblyInfo.cs 文献 添加另外一个存在的花式到您的工程 — 此次导航到 AssemblyInfo.cs，把它拖动到项缠绵“属性”文献夹下，然后包含到花式中还有另外一件事您需要作念。 在处置决策资源经管器中，右击 GuyTest 并在菜单栏中聘用属性 掀开花式属性页。点击“生成”标签，并 选中“ XML 文档文献”这个的复选框。 指定其文献名为 Guy.xml。
点击用具栏上的全部保存按钮来保存您的花式。当今这个项生分红的 Guy.dll 和 Guy.xml 文献和您之前用 CSC 定名生成的文献一样。不仅如斯，要是您需要，您还不错在结尾台高唱窗口使用 MSBuild 高唱来编译它 — 只需要传递一个 GuyTest.csproj 参数。
当今回到 Sandcastle Help File 生成器，在文档源目次下右击 Guy.dll ，并聘用从菜单中移除。 然后对 Guy.xml 作念一样的操作。
终末， 添加 GuyTest.csproj 到文档源目次下， 它在 Visual Studio 为您创建的文献夹下。点击用具栏上的全部保存按钮来保存 GuyTest.shfbproj。
当今您不错重新运行 Sandcastle，或者使用 Sandcastle Help File Builder 或者 MSBuild。此次，它将生成调换的文档，但是它是利用 .csproj 文献而不是您使用 CSC 高唱生成的 DLL and XML 文献。
领先，您需要生成 DLL。您不错在 Visual Studio 进行生成 — 或者，要是您需要，您也不错无须 Visual Studio 来生成，而是用 MSBuild 高唱进行生成。底下是我使用 MSBuild 高唱来生成 DLL 时的代码。这里需要传递 GuyTest.csproj 文献的完满旅途给 MSBuild 高唱。综合：请确保您指定的旅途是正确的！同期要是有任何空格，请用引号 "" 把它们包括起来。
生成的文献如下：
接着我使用 MSBuild 重新编译 GuyTest.shfbproj 。生成的 HTML 文档和上头的一样，不外，此次我使用的文献源是 C# 的类库花式文献。
作家先容：
Andrew Stellman 是《 Head First C# 》一书的作家萝莉 操，在 O'Reilly 出书社还出书过其他册本。了解更多对于 Andrew 的信息请掀开 Building Better Software。