在 ASP.net 的项目中生成 Sandcastle 用的 XML 文档

最近的项目准备结束了，代码里面一直是用 MS 推荐的注释格式。现在打算用 Sandcastle 来生成文档，但是 ASP.net 的项目和普通的项目不太同。一般项目都是可以在菜单“工程－属性”里面设置是否生成 XML 文档，但是 Web 项目没有这些选项。

在 MSDN 社区看到一个 MSFT 的版主 有个解决的办法。他的方法是在根目录下的 Web.config 中加入一个配置：

  <system.codedom>
    <compilers>
      <compiler language="c#;cs;csharp" extension=".cs"
          type="Microsoft.CSharp.CSharpCodeProvider, System,
                Version=2.0.3600.0, Culture=neutral,
                PublicKeyToken=b77a5c561934e089"
          compilerOptions="/doc:c:/app_code.xml" />
    </compilers>
  </system.codedom>

但是这样的话，因为所有的 .cs 文件都用这个配置，最终只会生成一个 app_code.xml 文件，里面的内容去不一定是 App_Code 里面的代码的内容而是要看最后编译的那个 cs 文件是哪个。他又提出为了防止这种问题，需要在每一个 aspx 文件里面加上，不同的文件的 outX 起来同的名字：

<%@ Page="" CompilerOptions="/doc:c:/outX.xml" %>

这样就可以给每一个文件都生成不同的 XML 文档。

但是这样也会产生其它的问题。本来我的项目中只生成一个 App_web_xxxx.dll 的（因为全部的 aspx 文件都在一个目录里面），但是这样单独配置后将会生成若干个 dll 文件。而且如果某个 aspx 文件忘记写了上面那句话，那么最终的 app_code.xml 文件的内容又会不对了。

经过我若干次尝试，发现还有更好的办法。在各个有 cs 文件的子目录下面建立一个 web.config 文件。在里面写上单独配置的代码，比如给 App_Code 的：

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
   
    <system.web>
        <compilation debug="true">
      <compilers>
        <compiler language="c#;cs;csharp" extension=".cs" compilerOptions="/doc:c:/App_Code.xml" type="Microsoft.CSharp.CSharpCodeProvider, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
      </compilers>
        </compilation>
    </system.web>
 
</configuration>

这样子编译的时候就会为 App_Code 目录里面的文件使用这个 Web.config，而不会受其它的编译配置的影响，也不会影响其它目录的编译配置。

关于 compiler 里面的编译选项还有更多的参数，参见 MSDN 中的相关内容 。