How to Build Help For a Web Site Project
Visual Studio has two different types of project models for creating web sites. Web Site Projects
are created with File
> Web Site...
and Web Application Projects
are created with File
and then by selecting a Web Application Project
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
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
- Download the latest Documenting Web Projects release in the Sandcastle Styles project.
- Download and install Microsoft's Web Deployment Project Add-In if you haven't already.
- Create a new Web Deployment Project for your Web Site Project:
- Right-mouse click your web site in Solution Explorer and click Add Web Deployment Project.
- Choose any name and location and then click OK.
- Add a new Web Configuration File to the web site if one doesn't already exist.
- 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.
- Build the Web Deployment Project to produce managed assemblies and optional XML documentation files that your DocProject or DocSite can reference.
- 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
to build help for your Web Site Project
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.
- 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.
- Open the DocProject Properties window for your project by right-mouse clicking the project node in Solution Explorer and selecting DocProject Properties.
- Find the Build | External sources property and click the ellipses button to open its dialog.
- Click to focus the first row in the Source column and then click its ellipses button (...), and then Select a folder....
- Browse to the folder that contains your assemblies and click Open.
- 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.
- 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.
- 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.
- Click OK.
At this point you can build your DocProject
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
will be referencing the latest assemblies and documentation.