Re: Generate code documentation xml for ASP.NET 2.0 website

Discussion in 'ASP .Net' started by carlj, May 31, 2006.

  1. carlj

    carlj Guest

    Back in Feb I posted a question about generating the XML file for
    source code comments in an ASP.NET website. I then posted a solution
    that I found. I have since been asked to provide further details, so I
    have written a detailed article (including source code) in
    http://www.carljohansen.co.uk/codelib/copyappcodexml . I hope this is
    useful to you if you have encountered the same problem that I did.

    Carl.
    -----

    Here are my original posts:

    [ I have an ASP.NET 2.0 website in Visual Studio 2005 (ie I open it
    with File
    | Open Web Site...). I have put XML comments in the source code in the

    App_Code directory (with <summary> tags, etc) and I want to turn these
    into
    XML files that can then be run through NDoc (along with app_code.dll)
    to
    produce help files. I've even found an (apparently stable) port of NDoc
    for
    v2.0 of the framework. So no problem, I'll just go to Project
    Properties |
    Compile and check the "Generate XML documentation file" box... uh-oh...
    this
    isn't a project, so there _is_ no Project Properties dialog. Hmmm,
    maybe
    "aspnet_compiler" has the /doc option... Nope. Wait, I know: I'll add
    "/doc+" to the vbc.rsp file so that it becomes a default compiler
    option...
    No dice; VS and aspnet_compiler use the /noconfig option, so they
    ignore the
    defaults. Now what? Does this mean I can't put things in App_Code if I
    want
    to document them?

    If that's too easy for you, then how about the same question for
    code-behind
    files? This one was easy in Visual Studio 2003, because these were
    built
    into one big /bin assembly. But in VS 2005 there seem to be two issues:
    (1)
    no Project Properties, so no way to set the "generate XML documentation

    file" option, and (2) no obvious assembly containing the code-behind
    code
    that I can give to NDoc. ]

    ....

    [ To answer my own question (for VB App_Code directories): I found a
    kludgy workaround. I added a <compilers> section to my web.config (by
    copying what was in my default machine.config). In it I added a
    <compilerOptions> element with "/doc+" as an option. This means that
    when I build the site using VS or aspnet_compiler, a file called
    App_Code.xml is placed in the same random directory under
    C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files
    as App_Code.dll. If you are using aspnet_compiler with an explicit
    target directory, you will find that App_Code.dll gets copied to the
    target directory but App_Code.xml doesn't. I wrote a post-build script

    to search in Temporary ASP.NET Files and copy the latest version of
    App_Code.xml (since the exact location sometimes varies from build to
    build)

    I suspect that this trick would not work with a C# site, because in C#
    you don't have the "/doc+" option; you have to specify a filename for
    the xml doc file. Since the VS/aspnet_compiler build processes consist

    of multiple invocations of the compiler, only the last invocation's xml

    file would be available. ]

    Please see http://www.carljohansen.co.uk/codelib/copyappcodexml
     
    carlj, May 31, 2006
    #1
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Carl Johansen
    Replies:
    3
    Views:
    7,523
    Deceth
    Jan 15, 2009
  2. D. Alvarado
    Replies:
    0
    Views:
    513
    D. Alvarado
    Apr 28, 2004
  3. Qun Wang
    Replies:
    0
    Views:
    385
    Qun Wang
    Apr 21, 2006
  4. =?Utf-8?B?RXJpYw==?=

    XML documentation for website

    =?Utf-8?B?RXJpYw==?=, Jun 28, 2007, in forum: ASP .Net
    Replies:
    5
    Views:
    407
    =?Utf-8?B?RXJpYw==?=
    Jul 5, 2007
  5. Matt
    Replies:
    3
    Views:
    346
    Bob Barrows [MVP]
    Apr 23, 2004
Loading...

Share This Page