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.