DocSite ASP.NET Web Application Example and Sandcastle vs2005
are used to create Visual Studio projects that build compiled help for their project references
(references to other projects in the same solution) and/or external
sources. When a project based on a DocProject
template is built, it produces a managed assembly and then its sources are built into a single compiled help file.DocSite Templates
are DocProject Templates
that also generate AJAX-enabled ASP.NET Web Application
build a fully-functional, interactive website for users to browse project documentation over the web or on your company's intranet.
To get started building a DocSite
right away, see the Creating a DocSite (Quick Start)
Some of the features of DocSites
- Familiar, AJAX-enabled ASP.NET Web Application project in Visual Studio that you can customize.
- Full support for ASP.NET themes (comes with one theme named, BasicBlue that has images, stylesheets and .skin files).
- ASP.NET Master page and a componentized layout with user controls.
- ASP.NET localization is used to provide resource-based text for all pages and user controls.
- Interactive, hierarchical table of contents with active topic highlighting.
- Filterable index with active file highlighting.
- Resizeable by dragging its handle with the mouse.
- Persistable, so that the user's placement of the handle is recalled upon the next visit to the website.
- Save, Bookmark, Email and Print buttons that act on the current topic. (Save and Bookmark are only visible in IE.)
- Customizable and highly extensible full-text search built from the ground up:
- Capable of indexing HTML files but customized specifically for searching against HTML topic files generated by Sandcastle.
- Extensible using .NET 2.0 Providers
- The default provider generates and uses an in-memory search index.
- Supports complex queries against the index, including operations such as AND, OR, - (not), and parenthetical grouping.
- Customizable, factor-based weight and rank calculations.
- URL query string supports bookmarking searches.
- Keyword browse page for live browsing of the search index (also supports a URL query string for bookmarking).
- Site administration page for configuring DocSite options, search factors and for viewing simple search statistics.
- Auto-generated header with site logo, project name and company name.
- Link to download the compiled help file (.chm).
- Scrollable content area that displays the active HTML topic file.
- Auto-generated footer with copyright information.
- Hackable URLs (currently based on a query string, not URL redirection).
There are some extra requirements that you must consider if you are going to use the DocSite
templates in Visual Studio 2005:
Visual Studio 2008
For Visual Studio 2008 users, only Standard edition or higher is required. Support for Web Application
projects and AJAX Extensions are built-in.
templates are available in two languages: Visual C#
and Visual Basic.NET
. Each DocSite
template produces the exact same output; they are just written in different languages.
The language that you choose for your DocSite
project does not affect which projects you can build compiled help for, in terms of language.
For more information, see DocProject Templates, Template Languages
templates build a website that has been tested for compatibility with the following web browsers only:
- Firefox 220.127.116.11
- Opera 9.24
- Windows Internet Explorer 7.0.6000.16575
- Microsoft Internet Explorer 6.0.2900.2180; SP2
Earlier versions of MSIE such as 5.5 have not been tested and may not be compatible.Frame Layout
Layout is accomplished using Cascading Style Sheets (CSS) and DIV tags, without any HTML tables. For the layout to work correctly in older versions of Internet Explorer, such as 6.0, the style sheets have rules that use CSS Expressions (an MSIE-only feature) and extensive use of the !important
declaration to override such rules in the more standard-compliant browsers such as IE 7.0, Firefox and Opera.
The layout HTML can be found in the DocSite.Master
page and each individual section of the frame is encapsulated in a user control found in the Controls
produce XHTML 1.0 output, mostly generated dynamically by ASP.NET controls.
DocSites can be deployed in the same way as any other typical Web Application
project. For example, you can manually copy the required files and folders to a host web server, or you can use Visual Studio's Publish
feature to make deployment easier. Another, recommend option is to use the Sandcastle/Deployment Build Engine Provider
to automate deployment.
For more information, see How To Deploy a DocSite
Windows Security Issue
templates generate a default header with a direct link to download the compiled help file (.chm) from the web server. Due to security restrictions on Windows operating systems, you must save the file to disk instead of opening it immediately.
When the browser prompts you to Open or Save
, choose Save
. Once the file is saved to disc, double-clicking it will result in an Open File - Security Warning
dialog asking, Do you want to open this file?
. Clicking Open
will open the Help
dialog but you'll see a message similar to the following in place of the content for every topic: Navigation to the webpage was canceled
To fix this issue you must:
- Right-mouse click the file and select Properties.
- On the General tab press the Unblock button.
- Click OK on the file properties dialog.
Now, double-clicking the file should allow you to see all of the html topics as expected.
HTML and other "unsafe" text can be entered into the site's search box since the ValidateRequest
property has been disabled for all pages in the application. This is done in the web.config
file, not each individual page.
templates handle post data appropriately when it's received through the search box in the header by parsing it and HTML-encoding it for display; however, if you extend the template by adding additional input controls then you must make sure to validate user input yourself to prevent against hacks and possible injection attacks.
For more information, see HttpRequestValidationException Class
DocSite Administration Page
The DocSite Administration
page provides a set of configurable options with application-wide scope. The administration page can be used in ASP.NET's local web server for configuring the site, before deployment, and it can also be used live on the web server, after deployment.
To access this page click the Admin
link in the top-right corner of your DocSite
. If you haven't logged in yet then you will be brought to the login page first. Enter the credentials that you configured when the project was first created and then click the Login
button to continue.Credentials
When you create a new DocSite
in Visual Studio, DocProject's New Project Wizard
will have a step that asks you for the DocSite
's administrative credentials. It stores them in the web.config
section and automatically encrypts the password using the algorithm that is configured in the same section (SHA1
in the DocSite
templates that ship with DocProject).
If you've created your own DocSite
template and would like to have the New Project Wizard
prompt for credentials, then add a user with the name, $admin$
to your template's web.config
file. Also, set the appropriate password format (e.g., SHA1
) and the wizard will automatically use it when storing the password. Here's an example:
<forms loginUrl="~/DocSiteLogin.aspx" timeout="10" slidingExpiration="true">
<user name="$admin$" password="" />
For more information about custom templates, see the Creating New Templates
Settings are stored in the DocSite.config
file found at the root of the project. Changes made directly to this file will not take effect until the application is restarted; therefore, use the web interface to configure settings whenever possible so that the application does not have to be restarted. If the application is restarted then the entire in-memory search index must be regenerated.Categories
There are two main categories in the administration page: General
Changes to options in both categories are applied immediately, although changes to the full-text search index, such as keyword weight
factors, require the index to be regenerated by clicking the Create Index
link. The Create Index
link is also useful for ensuring that the index is generated immediately after the DocSite
has been published to a production web server.
In the next section of this document each setting is listed with a short description of its purpose.
General settings apply to general features of the DocSite
application for all web users. As more configurable features are added to the DocSite
templates there may be more settings added in this section of the administration page.
Settings that directly affect web users and DocSite
|Letter Bar||Configure the characters that will appear in the letter bar at the top of the browse index page. Add characters from your native language or remove existing characters without having to modify any code.|
|Sidebar size persisted||Controls whether a cookie will be used on the client to remember the last position of the sidebar's handle. This setting is enabled by default.|
category has a few subcategories for viewing statistics and managing the full-text index, as well as settings related to the DocSite
search and browse pages.
Read-only, full-text search index statistics.
|Provider name||Name of the current search index provider. DocSiteMemorySearchProvider is currently the only implementation that is installed by DocProject; however, expect an SqlSearchProvider in a subsequent release.|
|Last creation date||The last date and time that the index was created.|
|# keywords||The total number of distinct keywords found among all documents that were indexed.|
|# documents||The total number of files that were indexed.|
General index-related settings.
|Root search path||Virtual path of the root directory in which the provider will begin the search, recursively. It's recommended that you do not change this setting; a different value may have unintended consequences.|
|Public search enabled||Indicates whether unauthenticated users can use the full-text search page. This setting is enabled by default. Note: The search page and the search box in the header are always available to authenticated users regardless of this setting.|
|Public browse enabled||Indicates whether unauthenticated users can use the index browse page. This setting is enabled by default. Note: The browse page and the search box in the header are always available to authenticated users regardless of this setting.|
Related to keywords indexed in files and keywords in search queries that are entered by web users.
|Minimum keyword length||Defines the minimum number of characters that a word must contain in order to be included in the index. This setting is also used to ignore words in queries that have fewer characters than the specified value. The default value is 2.|
|Excluded keywords||Comma-separated list of keywords that must be excluded from the index and queries.|
|Hot title keywords||Comma-separated list of keywords that have special semantics in the titles of indexed documents and are used to add additional value to matches in query results through the Title Rank Factors values, described below. You can customize this list if you want to improve search results with queries that contain full or partial matches to these particular words when found in titles.|
Weight factors are integers that affect the weight
of indexed keywords. Note that weight
is calculated while the index is being created and rank
is calculated when a keyword matches a search query. The values in this section do not set rank
directly; however, the weight
of a keyword does add additional rank
|Early position keyword||Factor used to calculate the weight of a keyword depending upon its location in the document being indexed. Typically, the earlier the position the higher the weight. The formula used to calculate weight is: keyword position / source length * -value + value where value is the value of this factor, which is 10 by default.|
|Title keyword||Factor used to calculate additional weight for keywords found in the titles of indexed documents. The base weight of title keywords is the value of the Early factor (described above), but calculated relative to the keyword's position in the title, not the entire document. The value of this factor is then multiplied by the result. The default value is 1.2, which gives 20% more weight to keywords found in titles.|
Title Rank Factors
values for keyword matches that are found in the title of an HTML topic.
|Exact title hot keyword match||Additional rank for exact keyword matches found in both the title of an indexed document and the Hot title keywords list (described above). The default value is 250.|
|Partial title hot keyword match||Additional rank for partial keyword matches found in the title of an indexed document, with an exact match found in the Hot title keywords list (described above). The default value is 100.|
|Exact title keyword match||Additional rank for exact keyword matches found in titles of indexed documents. The default value is 50.|
|Partial title keyword match||Additional rank for partial keyword matches found in titles of indexed documents. The default value is 20.|