Documentation for ASP.NET AJAX Beta 1 site (https://ajax.asp.net/docs/) using Sandcastle code base

  • Article

ASP.NET AJAX Beta 1 now available @ https://ajax.asp.net is the culmination of a 1 year cycle since our initial public CTP at PDC in 2005 and is the result the wonderful feedback from all of you in our community. With this release customers can begin building applications using the framework that will be fully supported at RTM and help elevate the quality of Web applications on the Web.

The ASP.NET web site supports the community with late breaking news, tutorials, and support forums and also lets the public preview upcoming releases through the Consumer Technology Preview (CTP) program. Until recently, all of the content for the site was maintained separately from regular Microsoft content. Normally documentation destined for MSDN and product help files uses an in-house content management system (CMS), to help writers and editors with the workflow, versioning, and localization tasks for producing the “official” product documentation. The ASP.NET AJAX Beta 1 (formerly ASP.NET “Atlas”) was the impetus for finding a way to publish prerelease content directly from our CMS to the web.

Using Sandcastle as a base, allowed us to quickly develop a tool that transforms XML based content combined with reflection data into a web site (https://ajax.asp.net/docs/). A PowerShell script drives the entire process. We first extract data from our CMS system into XML files that Sandcastle can process. Sandcastle then transforms the reflection data and content files into .aspx pages and a web.sitemap file, which combined with a master page, style sheets and other scaffolding becomes the ASP.NET AJAX documentation website.

We chose to go with .aspx pages (instead of plain HTML) to gain more control over the rendering of the final output and to allow us to easily change the look and feel of the site in future updates. Using .aspx pages also gives us the option to easily integrate the output from Sandcastle with other content not stored in our content management system.

Behind the scenes, the .aspx pages we generate only contain the actual page content. A master page provides a container for the header, breadcrumbs, and a table of contents. The table of contents gets displayed with a asp:TreeView control bound to the sitemap generated by our transforms. The breadcrumbs are rendered using a simple function that traverses the sitemap to the current node, but omits category nodes that don’t link to any documents.

We also added a feature to show live code samples that allow visitors to run web based samples and to view all of the related source code in a pop-up window. For an example take a look at “Using the UpdatePanel Control in ASP.NET AJAX Pages” (https://ajax.asp.net/docs/tutorials/creating/default.aspx).

ASP.NET AJAX Beta1 Details:

This release includes a number of significant changes:

1) An update to https://www.asp.net/ and https://ajax.asp.net/ to support the release

2) A comprehensive whitepaper detailing changes between the CTP’s and Beta

3) A simple to follow migration guide to help developers

4) Updated documentation generated using Sandcastle code-base

5) A revised ASP.NET AJAX Control Toolkit

This release is composed of three parts:

1) The Beta of the soon to be fully-supported ‘core’ ASP.NET AJAX functionality

2) A new CTP of additional functionality that runs on top of the Beta ‘core’

3) A new ASP.NET AJAX Control Toolkit that runs on top of the Beta ‘core’ and new CTP

Also please see a comprehensive blog post by Scott Guthrie.

Cheers.

Anand..