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:
- 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 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.
- 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 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.