Publish to hosted ASP.NET 2.0 location

Topics: DocSites, Sandcastle
Oct 24, 2008 at 3:03 PM
Edited Oct 24, 2008 at 3:19 PM

first of all: Dave, respect for the impressive tool you've created. I really like DocProject and it has become my favorite tool for help document generation.

But, i've stumbled upon a hurdle that I cannot seem to get around:
I need to publish the content of a DocSite project to a hosted ASP.NET 2.0 environment, and do not seem to get it working.
I would really loveto use DocProject for this matter, and thus wonder if there is someone else that has done this before?

Some questions:

  • Is it possible to publish everything into a subfolder?
    And thus keeping the App_* folders tidy and separated?
  • Is it possible to use a source-only deploy?
    I do not know for sure if my provider allows for compiled assemblies.

Many, many thanks in advance,

Peter Vrenken - MCPD: Enterprise Applications Developer - Sigmax Mobile Solutions
Mobile Development tools: HeadsUp | uTrack | ANit
Mobile technology: xTechnology |TransparaM | Pica.Mo


Oct 24, 2008 at 4:27 PM
Hi Peter,

There shouldn't be any problem with uploading a DocSite to a shared host that supports ASP.NET 2.0.

I think you may be able to upload just the source code instead of the compiled assembly, but doing so is not required or recommended.  I've never heard of a shared host that didn't support assembly binding to at least the typical probing paths such as the bin folder - this is a feature of .NET in general and I don't think it's something that can be disabled in the out-of-the-box CLR.

Here's some more documentation on the subject.  I'll probably merge this information into the DocSite Templates article in the future or maybe even create a separate How To article.

To prepare a DocSite for deployment:
  1. Read the Deployment section of the DocSite Templates article:
    1. 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 instead of the root folder then you may have to configure the subfolder as a separate web application on the host.  Many shared hosts provide a web interface for configuring nested web applications, although I've never actually tried this scenario with DocSites.
  2. Optional: Use the Sandcastle/Deployment build engine provider to add simple deployment capabilities to your DocSite.
    1. If you've already chosen the Sandcastle provider for your project then you may be able to get away with modifying the value of the BuildEngineProvider attribute in your DocSite project file to "Sandcastle/Deployment" without having to create a new project.  But if you decide to create a new project instead then you can use the Import Topics and Settings step of the New Project Wizard.
    2. Even with the Sandcastle/Deployment provider the initial deployment will have to be done manually because you'll have to upload many of the files that the provider doesn't automatically upload.  More on this below.

To deploy a DocSite:

  1. When you're ready to deploy your DocSite for the first time, use the Publish feature that Visual Studio offers to upload the structure and all of the files that are required to run the web application.  (Refer to the article mentioned in step #1 above for information about required files and folders.)
    1. It isn't necessary to build the documentation first because this step is just meant to get the ASP.NET-dependant folders and files onto the server, so if you want to publish before adding any documentation sources that should be fine.
    2. Having a VPN to the host is recommended for easy Internet deployment.
    3. If you need to use FTP instead, set the Publish target to a local folder and then upload the contents of the local folder to the host manually after publishing for the first time.
  2. If you've chosen the Sandcastle/Deployment build engine provider for your DocSite, open the DocProject Properties window and configure the deployment options.  Enter the target path, which can be an FTP URL, local path or UNC path, enter any credentials that are required, configure the proxy server options if applicable, choose from the deployment file types (more on this below) and set Enabled to True.
  3. Configure and build your DocSite as normal.
    1. If you've chosen the Sandcastle/Deployment build engine provider then your help system will automatically be deployed to the target server.  (See below for a recommendation on the file types that should be selected for automatic deployment.)
    2. If you are not using Sandcastle/Deployment then you must deploy the changes manually.  Make sure to upload the entire Help\Html folder, the App_Data\DocSiteContents.xml and App_Data\DocSiteIndex.xml files, and the entire bin folder as their contents may have changed.  (For more information about these files, refer to the article mentioned above in step #1 of To prepare a DocSite for deployment.)

Sandcastle/Deployment Notes

The Sandcastle/Deployment build engine provider will automatically upload your project's help system to the target server 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 itself, as mentioned in the instructions above.

The following list contains the file types that the DocSite template requires but that are not automatically deployed by the Sandcastle/Deployment plug-in:

  • .Master
  • .config
  • .skin
  • .css
  • .js
  • .gif
  • .jpg
  • .resx

You must deploy those files manually.  If you ever change them then you must deploy them again yourself.  (Don't forget to look for files of those types in subfolders as well.)

In a future release the Sandcastle/Deployment plug-in will have some new file type options that will allow it to automatically deploy an entire DocSite without any manual uploading required.  Here are a few possibilities:

  • Images category: gif, .jpg, .jpeg, .png, etc.
  • Script category: .js
  • Resources category: .resx
  • Support other common extensions in the ASP.NET category, such as .ashx.
  • DocSite category: combines the flags for all of the required categories into a single option.

For now, the recommended categories for DocSite deployment are as follows:

  • Chm (optional; although, when building Help 1.x it's recommended otherwise the Download Compiled Help link won't work.  Of course, it also won't work if you don't build Help 1.x.)
  • Html
  • AspNet (optional; useful if you may change one or more of the .aspx pages.)
  • ProjectOutput
  • DocSiteOutput

- Dave

Oct 27, 2008 at 11:58 AM
Edited Oct 27, 2008 at 3:38 PM

hello Dave,

thanks for the fast response and tons of information! I've done a publication, but it seems that the results has a Web.Config that targets ASP.NET 3.5. 

As far as i can see, the Web.Config in the DocSite project has also only 3.5 references. I am using Visual Studio 2008, but have to target 2.0 because of hosting limitations, so is there a option to configure on which version of ASP.NET the website should run? 

Thanks in advance,

Peter Vrenken - MCPD: Enterprise Applications Developer - Sigmax Mobile Solutions
Mobile Development tools: HeadsUp | uTrack | ANit
Mobile technology: xTechnology | TransparaM | Pica.Mo


Oct 27, 2008 at 3:22 PM
Hi Peter,

Visual Studio allows you to choose the target Framework version in the New Project Dialog.  But if you missed that you can also change it after the project has been created.

How to: Target a Specific .NET Framework

Note that after changing the target Framework version to 2.0 or 3.0 you may have to manually remove all references to .NET 3.5 assemblies.

- Dave
Oct 27, 2008 at 3:59 PM
Edited Oct 27, 2008 at 6:07 PM

hello Dave,

I've just checked, but this does not work for a new DocSite project.  :-(

I've just created a new DocSite project and the default Web.Config has both its type configurations and assembly references pointed to ASP.NET  v3.5.0 assemblies.

Does it work to completely replace the referenced assemblies and rewrite alle version information used everywhere to point to v2.0.0 assemblies?

Peter Vrenken - MCPD: Enterprise Applications Developer - Sigmax Mobile Solutions
Mobile Development tools: HeadsUp | uTrack | ANit
Mobile technology: xTechnology | TransparaM | Pica.Mo


Oct 27, 2008 at 8:12 PM
Hi Peter,

You are correct.  It seems that Visual Studio doesn't automatically update the web.config file for the target Framework version that you choose in the New Project dialog.  I think this is a limitation of user project templates.

However, changing the target Framework version from the standard Properties dialog for an existing DocSite worked fine for me.  Visual Studio intelligently cleaned up the web.config file, removing all .NET 3.5 Framework references while leaving the customized DocSite sections.  I didn't try building the project although it looks like it should work.

Try it this way and if you have any other problems please let me know.

- Dave
Oct 28, 2008 at 12:06 AM

Hello Dave,

There also seem to be some problems in the Controls folder. After changing to the 2.0 Framework the controls in this folder do not work anymore because of some 3.5 dependency. It seems that some default controls are only available in the 3.5 Framework. One example is the UpdatePanel.

Any advice?  

Peter Vrenken - MCPD: Enterprise Applications Developer - Sigmax Mobile Solutions
Mobile Development tools: HeadsUp | uTrack | ANit
Mobile technology: xTechnology | TransparaM | Pica.Mo


Oct 28, 2008 at 1:21 AM
Edited Oct 28, 2008 at 1:23 AM
Hi Peter,

Yep, correct again :)  Thanks for pointing out these issues.  This thread will probably help others as well.

See the Requirements section of the DocSite Templates document for a link to download ASP.NET 2.0 AJAX Extensions 1.0:

(On the download page make sure that you get the 1.0 Extensions.)

This stuff is built-in to the .NET Framework 3.5 so a separate installation is not required.

I'll make the Requirements section clearer by adding a subsection for something like, "Requirements for Visual Studio 2008 projects that target the .NET Framework 2.0 or 3.0".

- Dave

Don't forget to add an assembly reference to the extensions library and make sure that Copy Local is set to True for the reference in the Properties tool window.