How To Deploy a DocSite

Introduction

DocSite Templates provide a web user interface (UI) that acts as a container for the web-ready help system that Sandcastle generates.

A DocSite is actually an ASP.NET Web Application project so it requires a web server to run, such as Visual Studio's development server (WebDev), which is started when you press F5, or Internet Information Services (IIS), which is available as a built-in Windows Component on many versions of Windows (although sometimes it must be enabled).

DocSites may be public facing Internet websites, hosted by either a dedicated or shared server, or they may be internal websites hosted by an organization's intranet web server. Deployment to any of these targets can work the same way, although what typically differs is the mechanism chosen to deploy the files.

Deployment Scenarios

DocSites can be deployed in the same way as any other typical Web Application project.

File Transfer Protocol (FTP) is a common type of transport used when deploying files to a dedicated or shared Internet server. A Virtual Private Network (VPN) connection and a new drive mapping is a common way of deploying files to a dedicated Internet server or an intranet server on the company's Wide Area Network (WAN). A common way to deploy files to an intranet server on the Local Area Network (LAN) is to use a Universal Naming Convention (UNC) path, such as \\my-server-name\share-name\path, or a mapped drive.

When using a local or UNC path, one common approach to deploying a Web Application project is to right-mouse click the project in Solution Explorer and then click Publish.... This deployment feature of Visual Studio does not require any additional effort on your part to have all of your DocSite's required files deployed to a web server. However, when the help system is changed during a help build, you must manually perform a Publish operation again to keep the files up-to-date on the host.

For more information, see How to: Publish Web Application Projects.

Automation

Automating deployment means that changed or generated files will be automatically deployed to the target server after each build.

Web Deployment Projects

On a build server it's not reasonable to have to manually publish files that have changed during a build. As an alternative to Visual Studio's Publish feature, Web Deployment Projects (VS 2005, VS 2008) may be used to automate DocSite deployment after builds.

Note: Setting up a new Web Deployment Project may require some fine-tuning and knowledge of the files and folders that a DocSite requires at runtime.

Sandcastle/Deployment Build Engine Provider

The Sandcastle/Deployment Build Engine Provider automates deployment of the help system, which is the output of all DocProject Templates, including DocSites. This provider is not a requirement for deploying DocSites, although it is recommended.

When creating a new DocSite, simply choose the Sandcastle/Deployment build engine as the first step in the New Project Wizard. Since it derives from the Sandcastle build engine it provides all of the same features, but it also includes options for automated deployment.

Note: For help creating a custom build engine provider that inherits from the Sandcastle build engine provider, see the Creating a Build Engine Provider tutorial.

Limitations
There are some limitations when using the Sandcastle/Deployment provider:
  1. FTP: Automated deployments require the exact source folder structure to already exist on the server. This means that a one-time manual deployment is required to create the appropriate folder structure. Subsequent deployments may then be automated. (Steps for this are specified below.)
  2. UNC: A bug in DocProject 1.11.0 RC prevents a UNC path from working correctly, although there are workarounds available; see the discussion, Deployment URI Format.
  3. Local path format: There are no known issues when using a local path as the target, such as G:\wwwroot\MyDocSite\. Local paths can be used to specify a location on the local computer or a drive mapped to a computer on the LAN or over a VPN. Using a local path is therefore always the recommended approach, whenever possible.

Required Files

The following files and folders must be deployed.
  • .ascx user controls. For example, you must deploy the controls in the Controls folder.
  • .aspx web pages.
  • folders that begin with App_ are special ASP.NET folders that must be deployed; e.g., App_Data, App_GlobalResources, App_LocalResources and App_Themes. Look for App_ folders under subfolders as well.
    • App_Data\DocSiteContents.xml contains the XML used to generate the DocSite's table of contents (TOC). It must be deployed although it might be hidden from the project (you can use Show All Files to show it in Solution Explorer).
    • App_Data\DocSiteIndex.xml contains the XML used to generate the DocSite's index. This file might also be hidden like the DocSiteContents.xml file.
  • Images, Icons, Styles and Scripts folders, including those found in the Help folder.
  • the Help 1.x build output (.chm file), if you've configured your DocSite to produce one, will be located in the Help\bin folder. (It may be hidden.)
  • the Help\Html folder, which contains all of the topics that may appear in the DocSite's content area. (It may be hidden.)
    • Note: The Help\Html2 folder, if you've compiled Help 2.x, is not used by the website and does not need to be uploaded to a deployment web server.
  • the managed assembly that is created by the project, which is found in the output folder; e.g., bin\Debug\MyDocSite.dll
  • the DaveSexton.DocProject.DocSites.dll assembly.
    • Note: This assembly is located in your system's global assembly cache (GAC), installed by the DocProject installer. It is automatically copied to the DocSite's output folder (e.g., bin\Debug) when the project is built.
The following list provides some examples of files and folders that do not have to be deployed.
  • Source code.
  • Code-behind files for controls and pages.
  • Conceptual topic files in the Help\Topics folder.
  • Settings files in the Help\Settings folder.

Preparing a DocSite for Deployment

No preparation is necessary when using Visual Studio's Publish feature to manually deploy the web site to a host web server. To use this feature simply build the DocSite and then publish it when the build completes.

To automate deployment, the Sandcastle/Deployment provider will automatically deploy your project's help system at the end of each build; however, it will not upload all of the files that are required to run the ASP.NET web site. For this reason you must manually upload the structure and files that are required by the web application before the DocSite is built for the first time. This can be done using Visual Studio's Publish feature, which provides a UI that allows you to easily copy all of the required files and folders to the web server at once.

The following list shows all of the file types that are required by DocSites but are not automatically deployed by the Sandcastle/Deployment provider.
  • .Master
  • .config
  • .skin
  • .css
  • .js
  • .gif
  • .jpg
  • .resx
Building a DocSite will never effect any files of these types, nor will new files of these types get deployed by the Sandcastle/Deployment provider, so they must be deployed manually if you change them. Typically these types of files are not changed in a DocSite after it's created, with the exception of the DocSite.config file, which is used to store various administrative settings.

When using a local or UNC path, Visual Studio's Publish feature is the recommended approach to deploying these file types. If you are deploying to an FTP server, it is recommended that you use the Publish feature to copy the web application to a directory on your local computer and then use a third-party FTP program or Windows Explorer to copy the published application to the web server.

In a future release, the Sandcastle/Deployment plug-in will have some new file type options to allow for automated deployment of an entire DocSite without any manual uploads required. Here are a few possibilities for new categories:
  • Images: gif, .jpg, .jpeg, .png, etc.
  • Script: .js
  • Resources: .resx
  • ASP.NET (additional file types): .ashx, .Master, .config, .skin
  • CSS: .css
  • DocSite: Combines the flags for all of the required categories into a single option.
For more information on configuration options, see How To Configure DocProject.

Directory Structure

You must maintain the same directory structure on the host as you have on your local computer.

If you uploaded the DocSite to a subfolder of your web site instead of the root folder then you may have to configure the subfolder to be a separate web application on the host server. Many shared hosts provide a web interface for configuring nested web applications. On dedicated hosts and local hosts, when using IIS, you can add the DocSite root folder as a nested application.

Sandcastle/Deployment Configuration

You must manually enable deployment in the DocProject Properties window after a new DocSite is created. To enable deployment, set the Deployment > Enabled option to True.

Also make sure to set the Target path and any authentication/proxy settings that may be required.

Sandcastle/Deployment offers several file type categories for automatic deployment. The following list contains the recommended categories that should be enabled for DocSite deployments.
  • Chm: This category is optional; although, when building Help 1.x it's recommended otherwise the DocSite's Download Compiled Help link won't work.
  • Html: Help 1.x HTML output folder.
  • AspNet: This category is optional. It's useful if you ever decide to modify one or more of the DocSite's .aspx pages.
  • ProjectOutput: Assemblies in the bin folder.
  • DocSiteOutput: XML files in the App_Data folder.
For more information on configuration options, see How To Configure DocProject.

Deploying a DocSite

Once you have prepared for deployment, you will be ready to deploy your DocSite to a web server.

Configure and build your DocSite normally. There are no restrictions as to what files you may include in your DocSite Web Application or in the contents of your help system.

To deploy with Sandcastle/Deployment:
If your DocSite is using the Sandcastle/Deployment build engine provider and deployment is enabled then your help system will automatically be deployed to the target web server at the end of each help build.

For more information, see Sandcastle/Deployment Configuration above.

To deploy without Sandcastle/Deployment:
If you are not using Sandcastle/Deployment then you must deploy the changes manually using Visual Studio's Publish feature or you can use a Web Deployment Project.

For more information, see Deployment Scenarios above.

Always make sure to upload the entire Help\Html folder, the App_Data\DocSiteContents.xml and App_Data\DocSiteIndex.xml files, the entire bin folder and the Help\bin\{docset-name}.chm file since their contents may have changed.

Last edited Dec 12, 2008 at 4:15 PM by davedev, version 1

Comments

No comments yet.