Quick Start: Creating a DocSite
DocSite ASP.NET Web Application Example
To get started building a new DocSite
, the following steps may be taken after the successful installation of DocProject, Sandcastle and
ASP.NET 2.0 AJAX Extensions 1.0
A separate AJAX installation is only required for Visual Studio 2005
Latest Release Notes
for more information and additional requirements.
For more information about DocSites
For more information about DocProjects
in general, see
Follow these steps to create a new DocSite
in an existing solution:
- Open a solution with at least one project for which you would like to create a documentation website.
- Any Visual C#, Visual Basic, Visual J# or Managed Visual C++ project is supported, including
Web Application projects; however, Web Site projects must be added as
external sources. See
How To Build Help For a Web Site Project for more information.
- Add a new project to the solution and select one of the DocSite templates.
- The templates can be located by selecting the language of your choice from the
Project Types list (e.g., Visual C# or Visual Basic).
- Expand the language node and select the DocProject subcategory.
- Look under the My Templates section in the Templates area.
- For this tutorial, choose a DocSite template.
- Note: If you receive an error that the project type is not supported then you must update Visual Studio 2005 for use with
Web Application projects. For more information, see
How To Configure Visual Studio 2005 For DocProject.
- When a new DocProject or DocSite is created, the New Project Wizard is launched automatically to help you configure your project. For more information, see
Configuring Projects with the New Project Wizard.
- In the first couple of steps you may choose any build engine and Sandcastle presentation style that you'd like.
- For information about the Sandcastle/Deployment engine, see
Sandcastle Deployment Plugin.
- In the step that offers compiled help you may choose Help 1.x, Help 2.x, both or neither of them. You can change this setting at a later time in the
DocProject Properties window or the
DocProject External UI. For more information, see
How To Configure DocProject.
- Make sure that you select one or more projects in the last step of the wizard before clicking
- If you clicked Finish without selecting any source projects then you can add them at a later time as
project references; e.g., right-mouse click the DocSite project in Solution Explorer, select
Add Reference... and then choose your DocSite's sources from the
- Note: If the projects that you'd like to document do not appear in the list then DocProject cannot use them as
project references; however, if they produce managed assemblies then you can reference the assemblies as
external sources later on using the External sources project option.
- Optionally, configure additional project options before building using the
DocProject Properties window:
- Right-mouse click the project node in Solution Explorer and select DocProject Properties.
- Use the Build > External sources project option now if you'd like to reference folders, individual assemblies, or raw reflection XML files as sources for auto-generated reference documentation.
- Note: The DocProject Properties window is only available in Visual Studio Standard edition and higher. Visual Studio
Express users can configure the project using the
DocProject External UI.
How To Configure DocProject for more information.
- Press Ctrl+F5 to build and view the DocSite or press F5 alone to build and attach to the website in debug mode.
You can work on the DocSite
as you would work on a normal Web Application
project, because that's exactly what it is. Feel free to modify the
files, for example.
The only DocSite
files that you shouldn't modify are the DocSiteContents.xml
files since they are recreated every time a Partial
build is executed. If you do decide to update these files, be sure to save a copy of your changes elsewhere so you can merge them with the regenerated versions the next time you perform a
that use the Sandcastle build engine contain other project items that should only be modified in certain situations. For more information, see the
For more information on Partial
You can replace the default Logo.jpg
file with your company's logo if you'd like without any other required modifications. The default image is 51x51 pixels in size. (The odd number, 51, allows for parts of the logo to be properly centered within
Company Name and Copyright
The company name and copyright information found in the header and footer are taken from the project's
file, found in the Properties
directory. To edit this file using the project's properties dialog, double-click the
folder in Solution Explorer
, select the Application
tab and click the
Hackable URLs are created by browsing to the root url and adding a query string starting with
. Append each topic name to
in parent-child order, from left to right, separated by slashes, and then finally the destination topic name that will be displayed, at the end.
Here is an example of a valid url that points to a topic named, Form1 Constructor
under a topic named,
, at the help system's root, Namespaces
- The tilde is an optional token that represents the application's root directory. This is useful for nesting applications.
- The symbol is a url-escape character that represents a single space. %20 is an alternative that may be used instead of the
- Leading and trailing spaces are valid in topic names, so make sure they are added to the urls using the + or %20 escapes.
If you have decided to use the Sandcastle
build engine (the only engine that ships with
), then please note that any changes you make to the Html Help Workshop
files will be lost the next time a
build occurs. The same goes for any of the files in the Html
directories as they are all generated by Sandcastle
build. However, you can freely update any of the files in the Icons
directories since they are only copied into the
by the wizard when it's first created and will not be affected by building the project. In fact, the files in these directories are used to build the compiled help, so you can update them to control
's output as you see fit.
For more information, see
Build Process, Sandcastle Project Items
Transforms and Content Folders
Files in the Transforms
folders, under the Presentation
folder, can be updated. They are not replaced when the project is built. Use these files to control the presentation of Sandcastle's HTML output.