Website project: want to generate XML documentation on build

问题

For legacy reasons, I'm maintaining a Web Site Project for which I want to provide up-to-date documentation from the XML documentation comments. I gather I can do that by tweaking the <compilers> section in web.config. I finally reached this point:

  <system.codedom>
    <compilers>
      <compiler
        language="c#;cs;csharp"
        extension=".cs"
        type="Microsoft.CSharp.CSharpCodeProvider"
        compilerOptions="/optimize /doc:C:\temp\my-output-here.xml"
        warningLevel="1" />
    </compilers>
  </system.codedom>

Now when I start the website with (and thus invoke just-in-time compilation) I do get an XML file in the requested location but it's minimal:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>App_global.asax.abqhzva4</name>
    </assembly>
    <members>
    </members>
</doc>

It seems like the <compiler> tag doesn't quite do what I want. It must be generating XML for the project folder itself rather than the .cs files, or it's getting overwritten with each compilation unit and I'm only seeing the trivial last one, or... I don't know. I'm not sure. This config tag is not well documented.

Long story short, I'm looking for a way to get XML documentation for all the .cs files in this website project. It doesn't matter if it's all in one file, in separate files, or even shoved into memory at run time.

I'm aware of the prior question on this, but the link provided there has been redirected to the Sandcastle site. That's great, but it's way more than I'm actually going to use on this project. Simply getting XML documentation at build time or run time is all that is necessary.

My question then is: What do I need to do to get the <compiler> config entry to generate XML docs for a Website Project?

回答1:

I have an ugly workaround as well... But here goes!

1. Download the latest Sandcastle Installer from this page - https://github.com/EWSoftware/SHFB/releases

2. Unzip and run the installer

3. Copy EWSoftware.CodeDom.dll into your website's \bin directory. The default location of this file is - C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\Extras\EWSoftware.CodeDom.dll

4. Modify web.config as follows:

<configuration>
  <system.codedom>
    <compilers>
      <compiler language="c#;cs;csharp" extension=".cs"
        compilerOptions="/docpath:C:\Publish\Docs"
        type="EWSoftware.CodeDom.CSharpCodeProviderWithDocs, EWSoftware.CodeDom"
      >
        <!-- NOTE: Change version value as needed (v3.5, v4.0, etc.) -->
        <providerOption name="CompilerVersion" value="v4.0"/>
      </compiler>
    </compilers>
  </system.codedom>
</configuration>

Source: http://ewsoftware.github.io/EWSoftwareCodeDom/html/40ba6bda-95d6-4a64-834f-f7cedcb589d1.htm

5. Rebuild your solution and voila! The folder specified with the /docpath option will contain your XML documentation.

来源：https://stackoverflow.com/questions/32656604/website-project-want-to-generate-xml-documentation-on-build

标签

visual-studio-2012

web-site-project

xml-documentation