Abstract

Geek's XML Kit is implemented as ASP.NET 2.0 HttpHandler compiled into DLL. The typical Geek's XML Kit pipeline is shown on the diagram.

Requirements

To check out this quick start you need:

Visual Studio ASP.NET Development Server
Downloaded Geek's XML Kit binary package
Some basic skills in XML\XSLT

Installation and Testing

In this section you will find instructions how to get Geek's XML Kit running with Visual Studio Development Server. The source code for this tutorial is included with binary package.

Create an “Empty Web Site”
Place GeeksXmlKit.XmlHandler.dll and Mvp.Xml.dll to the Bin folder

Add the following lines to Web.config in the <system.web /> section. With these lines you bind HttpHandler to .xmlx extension.

<httpHandlers>
   <add path="*.xmlx" 
        type="GeeksXmlKit.Web.XmlHandler, GeeksXmlKit.XmlHandler" 
        verb="*" 
        validate="false"/>
</httpHandlers>

Create in the root of your website index.xmlx file:

<?xml version="1.0" encoding="utf-8" ?>
<?xml-stylesheet type="text/xsl" href="index.xsl"?>
<page>
   <message>Hello, World!</message>
</page>

As you can see this is an simple XML file with referense to the index.xsl stylesheet.

Create in the root of your website index.xsl file:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet  version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<!-- Output settings -->
<xsl:output method="xml" 
	encoding = "utf-8"
	doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
	doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" 
	media-type="text/html"
	omit-xml-declaration="yes"
	indent="yes"
/>
	
	<!-- Starting point -->
	<xsl:template match="/">
		<xsl:apply-templates/>
	</xsl:template>

	<!-- Template for the <page> element -->
	<xsl:template match="/page">
		<html>
			<head>
				<title>Hello, World!</title>
				<meta http-equiv="Content-Type" 
				      content="text/html; charset=UTF-8" />
			</head>
			<body>
				<h1>
					<xsl:value-of select="message" />
				</h1>
			</body>
		</html>
	</xsl:template>

</xsl:stylesheet>

Note that you can specify any Content-Type for generated HTTP Request using media-type attribute of <xsl:output /> independently of method attribute. Thus very easy to generate valid XHTML-Strict code with Content-Type text/html.

If you run website and point you browser to index.xmlx file you should get this nice indented valid XHTML document:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html>
  <head>
    <title>Hello, World!</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  </head>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>

<!-- Page generated at: 13.05.2007 15:04:10 -->
<!-- Page generated in: 0,02  seconds -->

Note comments in the end. They are inserted by Geek's XML Kit.

Configuration

Geek's XML Kit has some nice features that are configured via custom config section in Web.config. This section will guide you throught all options you can configure assuming that you complete previous section.

Add the following lines to you Web.config into the <configuration> section to register Geek's XML Kit configuration section:

<configSections>
   <section name="geeksXmlKit" 
            type="GeeksXmlKit.Configuration.XmlHandlerConfigurationHandler,
                  GeeksXmlKit.XmlHandler "/>
</configSections>

The example configuration may look as following:
```
<geeksXmlKit
    showGenerationTime="true"
    showPageTimestamp="true"
    offsetUTC="3"
    cachePeriodInSeconds="120"
/>
```
The parameters are:
showGenerationTime
Show or not time spent on page generation in XML comment (default is true)
showPageTimestamp
Show or not timestamp of page generation useful for caching testing (default is true)
offsetUTC
Your local timezone offset (positive or negative), it is used for showing page timestamp generation in your local time (default is 0)
cachePeriodInSeconds
Maximum period in seconds for storing output in cache (default is 0 means caching off)

Running Geek's XML Kit on IIS

To use quick start sample on IIS you have to change IIS settings (or ask your hosting support staff to do this for you) to pass all requests to .xmlx files through the ASP.NET ISAPI extension. You can make wildcard mapping to ASP.NET ISAPI too.

Running entire site using Geek's XML Kit

To run entire site (like this one) using Geek's XML Kit you have to make IIS settings from previous section and set index.xmlx (or any other filename) to be default document for you site configuring IIS directly or using some control panel on your shared hosting. Unfortunatelly you have to make some additional configuration to get rid of issue with default document resolution on IIS6 (situation with IIS7 need to be checked).

I found two workarounds of this problem:

You can use .ashx extension for the files processed by Geek's XML Kit. I don't know why but it works, but breakes default .ashx handlers behaviour.

You can use some URL rewriter (for example UrlRewriter) to correct this issue. This method is used on this site:

<!-- This is IIS 6.0 workaround -->
<RewriterRule>
    <LookFor>~</LookFor>
    <SendTo>~/index.xmlx</SendTo>
</RewriterRule>

Protecting files

You can use standard ASP.NET 2.0 content protection techniques. For example, you can deny access to all .xsl files by adding this snippet to <httpHandlers /> section in Web.config:

<add path="*.xsl" verb="*" type="System.Web.HttpForbiddenHandler" />

Alternatively, you can protect any folder by placing this Web.config file in it:

<?xml version="1.0"?>
<configuration>
   <system.web>
     <authorization>
       <deny users="*" />
     </authorization>
   </system.web>
</configuration>

Live sites

Some examples are included into the binary package. You can get this site's sources using SVN client or browse repository with web browser.