Extracting documentation from ASPX files in a ASP.NET Web Site

Topics: User Forum
Jul 31, 2013 at 10:17 PM
Is it possible??? That's the big question.

We have large ASP.NET Web Sites with lots of annotations inside *.aspx files.
  1. When the aspx page has embedded C# or VB script, Visual Studio allows the insertion of XML annotation. Can that XML be extracted by Sandcastle for inclusion in the help file?
<script language="C#" runat="server">
string sql;
///////////////////////////////////////////////////////////////////////
/// <summary>
/// 
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
void Page_Load(Object sender, EventArgs e)
{
  1. Can annotation or code in the HTML of an ASPX page be extracted for inclusion in Sandcastle help?
Coordinator
Aug 1, 2013 at 3:22 AM
Give it a try and see. My guess is probably not since the code is most likely compiled on the fly when the page is requested and building the project will not generate any assemblies. No .\bin folder output means no XML comments output.

Eric
Sep 10, 2013 at 5:49 PM

How to document ASPX pages and related code-behind classes in Web Sites using Sandcastle and Aspnet_compiler.exe

_
Actually, it IS possible to use Sandcastle to document in-line code and code-behind classes for ASPX pages in a Web Site. One way is to publish the Website with fixed-assembly names for each file in the project. This creates a .dll assembly for all the code, including the in-line script within ASPX pages and their related code-behind classes. Here's how:

First build the Web Site as usual, adding the <codedom> compilers in the site's Web.config and the EWSoftware.CodeDom.dll in the project's bin folder. Be sure to use the absolute path for the /docpath location to publish the XML documentation. Note: The normal build does NOT produce assemblies for ASPX pages. That comes later.

Here's the configuration section for <system.codedom>. Note: Change the /docpath for each project and set the correct CompilerVersion for the project's .NET Framework version.
    <system.codedom>
        <compilers>
             <!--For C#--> 
            <compiler language="c#;cs;csharp" extension=".cs" compilerOptions="/docpath:C:\Publish\Docs" type="EWSoftware.CodeDom.CSharpCodeProviderWithDocs, EWSoftware.CodeDom, Version=1.1.0.0, Culture=neutral, PublicKeyToken=d633d7d5b41cbb65">
                <providerOption name="CompilerVersion" value="v4.0"/>
            </compiler>
             <!--For VB.NET--> 
            <compiler language="vb;vbs;visualbasic;vbscript" extension=".vb" compilerOptions="/docpath:C:\Publish\Docs" type="EWSoftware.CodeDom.VBCodeProviderWithDocs, EWSoftware.CodeDom, Version=1.1.0.0, Culture=neutral, PublicKeyToken=d633d7d5b41cbb65">
                <providerOption name="CompilerVersion" value="v4.0"/>
            </compiler>
        </compilers>
    </system.codedom>
Then publish the Web Site using "Aspnet_compiler.exe" from the command-line. One variation of the command looks like this:
This will overwrite the XML files in the /docpath location with new XML output for every page, class, module and file in the project. It also produces .dll assemblies for each file in the bin folder of the compiled target Web Site folder.
_
  • For Web sites using .NET 2.0, 3.0 and 3.5, use Aspnet_compiler.exe v2.0.50727
    • %windir%\Microsoft.NET\Framework\v2.0.50727
    • %windir%\Microsoft.NET\Framework64\v2.0.50727
  • For Web sites using .NET 4.0, use Aspnet_compiler.exe v4.0.30319
    • %windir%\Microsoft.NET\Framework\v4.0.30319
    • %windir%\Microsoft.NET\Framework64\v4.0.30319
For more information, see "How to: Generate Fixed Names with the ASP.NET Compilation Tool".
Also see "ASP.NET Precompilation Overview".
Coordinator
Sep 10, 2013 at 11:10 PM
Thanks for the info. I'll see about updating the related help topic with this info.

Eric