How to Build Help For a Web Site Project

Introduction

Visual Studio has two different types of project models for creating web sites. Web Site Projects are created with File > New > Web Site... and Web Application Projects are created with File > New > Project... and then by selecting a Web Application Project template.

Note: To use Web Application Projects in Visual Studio 2005 you must install Service Pack 1.

DocProject supports Web Application Projects in the same way that it supports other projects because a Web Application Project generates a managed assembly each time it's built. In fact, DocSite Templates are actually based on a Web Application Project template themselves.

Web Site Projects do not output an assembly or XML documentation file when they are built, but to generate a project's help Sandcastle requires a reference to the managed assembly and, optionally, an XML documentation file that contains your code comments. Since Web Site Projects do not produce an assembly, you may have already noticed that they don't appear on the Projects tab in the Add New Reference dialog.

Prepare a Web Site Project

Follow these instructions to setup your Web Site Project so that it may build an assembly and an optional XML documentation file for use with DocProject:
  1. Download the latest Documenting Web Projects release in the Sandcastle Styles project.
  2. Download and install Microsoft's Web Deployment Project Add-In if you haven't already.
  3. Create a new Web Deployment Project for your Web Site Project:
    1. Right-mouse click your web site in Solution Explorer and click Add Web Deployment Project.
    2. Choose any name and location and then click OK.
  4. Add a new Web Configuration File to the web site if one doesn't already exist.
  5. To produce XML documentation files for your web site you must make changes to the web.config file. Refer to the documentation in Documenting Web Projects for more information and example configurations.
  6. Build the Web Deployment Project to produce managed assemblies and optional XML documentation files that your DocProject or DocSite can reference.
    1. Important: If you make any changes to your Web Site Project then you must build this project again before you build your DocProject or DocSite. You can automate this by configuring the appropriate solution build dependencies.

Prepare a DocProject or DocSite

The following instructions will guide you to setting up a new DocProject or DocSite to build help for your Web Site Project.

Note: If you haven't done so already, follow the instructions in Prepare a Web Site Project above first and make sure that you build the Web Deployment Project at least once so that you have an assembly to reference.
  1. Add a new DocProject or DocSite to the same solution as your Web Site Project. See Creating a DocProject for a new Solution or Creating a DocSite (Quick-Start) for help.
  2. Open the DocProject Properties window for your project by right-mouse clicking the project node in Solution Explorer and selecting DocProject Properties.
  3. Find the Build | External sources property and click the ellipses button to open its dialog.
  4. Click to focus the first row in the Source column and then click its ellipses button (...), and then Select a folder....
  5. Browse to the folder that contains your assemblies and click Open.
    1. Note: Refer to the documentation provided by Documenting Web Projects for information about where to find the assemblies and XML documentation files that were generated for your Web Site project.
  6. Press the Tab key or simply bring the input focus away from the Source column and the XML Documentation column will be filled in automatically.
    1. Note: If you've configured the XML documentation files to be generated in a different location, then replace the current path with the path to your XML documentation files.
  7. Click OK.
At this point you can build your DocProject or DocSite and it will generate help for your Web Site Project. In the future, remember to build the Web Deployment Project again each time you make changes to your Web Site Project so that your DocProject or DocSite will be referencing the latest assemblies and documentation.

Last edited Jun 10, 2008 at 5:41 PM by davedev, version 8

Comments

davedev Sep 22, 2009 at 6:35 AM 
I appreciate your attempt to report issues with DocProject and I'm sorry for your frustration with the uninstaller, but this is not the right way to go about getting my attention. I monitor the discussions regularly so if you have questions I'd appreciate it very much if you'd please post there (but search the Discussions area and the Issue Tracker first as you might find some useful information).

Your comments, as well as my response, will be removed in a few days.

jfowler01 Sep 22, 2009 at 12:15 AM 
Even the uninstall won't fix it. What did you guys do to my Visual Studio? All I wanted to do is document an almost complete project. All day wasted and the solution is messed up!!!!!!!!! Ok, what did you add that the uninstall won't remove?

jfowler01 Sep 22, 2009 at 12:11 AM 
You don't care how bad you mess up a developer's world as long as you can put you name in the paper.....

jfowler01 Sep 22, 2009 at 12:00 AM 
And I thought the Install messed it up....just wait till you uninstall....Danger Will Robinson...Danger!

jfowler01 Sep 21, 2009 at 11:48 PM 
Beware, DocProject will mess up Visual Studio 2008 Team Systems BAD!

jfowler01 Sep 21, 2009 at 7:42 PM 
Just once I would like to use something related to Micrisoft that I don't have to debug someone elses code and spend hours setting up over-engineered, bug-ridden software and search google for hours finding a workaround....and then finally realize it was never going to work until the 3rd or 4th release....The Microsoft Way! !!!!!!!!!!!!C:\Program Files\Sandcastle\ProductionTools\MRefBuilder" process failed with exit code: 1. !!!!!!!!!!!

davedev Jun 10, 2008 at 5:23 PM 
A custom code provider is now available on the Sandcastle Styles project:
http://www.codeplex.com/SandcastleStyles

dcrowe Mar 26, 2008 at 11:53 PM 
I personally don't like the idea of adding the code to a library, because it hinders the code,run,code,run cycle.
I have proposed another solution in the issue tracker:
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=15818

Maria25 Feb 22, 2008 at 2:23 PM 
Hi,
I'm very interessted in this document, because I need to do the documentation for a website and not for a website aplication. I try to do all this steps but, I can't do my documentation, because when I try to prepare my web site project in the step 3, create a web configuration file, I don't know I have to do that and I can't continue. And rest of the step, I don't understand it so clearly. Could you give me any idea about that. Thank for all.

davedev Sep 6, 2007 at 9:39 AM 
Actually, this doesn't appear to work in a C# web site (I didn't try a VB.NET website though).

First, the code example is incorrect. Technically, it should look like this (for C#):

<location path="App_Code">
<system.codedom>
<compilers>
<compiler language="c#;cs;csharp" extension=".cs" compilerOptions="/doc:{config}/bin/{project}.xml"
type="Microsoft.CSharp.CSharpCodeProvider, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
</compilers>
</system.codedom>
</location>

However, after building the xml documentation file does not contain comments for code found in the App_Code folder. When changing the name (just in case one output would replace the other), no xml documentation file is found for the App_Code folder in the Web Deployment project's output directory or in ASP.NET's dynamic build output directory: %windir%\Microsoft.NET\Framework\v2.0.50727\Temporary ASP.NET Files\

If in fact this does work anyway for VB.NET I assume that you'd have to use a different file name for the App_Code document otherwise it will just be replaced (or replace) the other xml documentation output. If that's the case, then this solution isn't very useful anyway since the deployment project will _not_ copy the file with a different name so you'd have to go find it manually in the ASP.NET dynamic build output folder (path specified above). And then DocProject will not allow you to specify multiple xml documents for a single external source anyway, so you'd have to add some code to the build process component to retrieve the file and copy it into the build assembler's Comments folder so that it will be picked up by Sandcastle.

Obviously, it's just much easier to add the code to a class library, but thanks for trying :)

davedev Sep 6, 2007 at 8:54 AM 
Great, thanks!

base Aug 30, 2007 at 11:50 AM 
It is possible to document the App_Code directory. Just make use of the location tag. See example below.

<location path="App_Code">
<system.web>
<compilation debug="true">
<compilers>
<compiler language="vb;vbs;visualbasic;_vbscript" extension=".vb" type="Microsoft.VisualBasic.VBCodeProvider, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" compilerOptions="/doc:{config}/bin/{project}.xml "/>
</compilers>
</compilation>
</system.web>
</location>