iFinity

This is becoming a very common help request for me lately, as increasing numbers of people convert old html (and asp and php) based websites into DotNetNuke based websites to take advantage of the extra power of the DNN framework.  The problem occurs that many Html based websites have been around a long time and generally rank well in search indexes.  Typically, the site owner wants to make sure that none of that existing ranking and associated traffic is lost when converting to a new DotNetNuke site.

This post will cover all of the steps necessary to divert traffic away from an old html based website to a new, DotNetNuke based website.  If you have an old .asp or .php based website, the instructions are virtually the same with just the file extensions changed.

0. Do your backups.

You're going to be modifying the web.config file, so take a backup of this file before you start.  If you mess it up, getting it all back will be as simple as restoring your previous web.config file.

1. Install the Url Master software

You can download and install the software from the Url Master Product Page : it's free to trial, and if you are working on a live website, you can get a free trial licence to use on your live site.

Install the Url Master software as per the instructions.  Of course, this is going to change your site to use Friendly Urls, but if you're interested in maintaining your existing links, then you'll at least want to make sure they are supported, and this means friendly urls!   That's assuming you didn't name your existing .html files "tabid-123-ctl-view-display.htm" instead of "product-information.html" like a sane person.

2. Plan your redirects

If you have a series of .html files 'out there' indexed, bookmarked and generally known by people on the internet, you're going to want to capture those and '301' redirect them to somewhere else, should they be requested.  This does two things : by using a 301 redirect, you will update the Search Engine indexes to your new locations, and any users using an old link from a bookmark or other website will still end up where you want them to be.

However, if you're going to move away from existing known urls to new ones, you need to plan which ones to capture.  The easiest way to do this is to do a search in search engines for indexed pages.  A simple site:domain.com search in Google will turn up the majority of indexed links.  You can also go back through your site logs using an log analyser, or do a site search in Yahoo.  You may also be able to get a list of Urls from a webmaster console in Yahoo or Google.  This is the list of Urls you will redirect from.

Once you have a list of all the urls you need to capture and redirect, you need to have the new Urls to send them to.  It's often tempting to just redirect everything to the home page of your new site, but if you can, plan your new site so that it has logical places to send the old urls.  You should have at least rough categories like products -> new product page, contact -> new contact page, etc.

Make sure these new Urls are created in DNN so you can see the Urls you'll redirect to.

3. Map the relevant file extension to ASP.NET

This is the important part.  A little background : the extension on a request to your IIS webserver allows IIS to determine which piece of software installed on the webserver should handle the request.  If you request a .htm file, then IIS knows what to do with it : it just streams the file back out to the browser as is by reading it from the file system and sending it back out.  Same thing for Jpeg or Gif files : it sets the media type of the response, and then streams the binary image information back to the browser.  So far so good.  When your IIS server receives a response with the .aspx extension, it knows that it must pass that response to the ASP.NET software (called the ASP.NET runtime) installed on the server.  ASP.NET then handles the interpretation of the code within your .aspx file, and gives the results back to IIS, which ten steams them back to the requesting browser.  

There's nothing magic about the .aspx extension : Microsoft just decided on this because the previous generation of ASP used the .asp extension, and it needed a new one.  So they decided on .aspx and the rest is internet history.  The same principle applies to .axd, .ashx and all the other ASP.NET specific extensions.  All they do is inform IIS to pass the request along to ASP.NET for processing.

Now, DNN is just a program built using ASP.NET technology, so each and every request for DNN must be associated with the ASP.NET runtime files.  This is why the standard DNN Urls all end with /default.aspx : so that IIS knows that ASP.NET must be used to handle the request.

When you install the Url Master software, it gets run for each and every request that is handled by ASP.NET, and, by association, DotNetNuke.  If that sounds concerning to you, don't be worried, because the Url Master software has an efficient regex filter to ignore the requests it doesn't need to intercept.

Now, in order for the Url Master software to redirect your old .htm request to your new DNN page, it needs to know when that .htm request is made.  This is done by mapping the .htm extension to the ASP.NET runtime, so it behaves in just the same way as a .aspx page.

Concerned? You needn't be.  Although you can serve up html pages using the ASP.NET runtime, you won't even be doing that.  All that will be happening is that the .htm request will be intercepted by the Url Master software, it will decide where it should be redirected to, and the redirect will take place.  The whole redirect process is lightning fast.  And if you have a .htm page in your website that isn't a DNN url, then asp.net will just process it in the same way that IIS does - you, your server or your visitors won't be able to tell the difference.

Here's how you do that mapping:

IIS6

Go to your IIS Management page.

• open the property page for website / virtual directory.
• click the 'home directory' tab
• click the 'configuration' button, select the 'mappings' tab
• click 'Add' under the 'Application Extensions' list to add a new application extension mapping
• browse to the aspnet_isapi.dll (normally at c:\windows\microsoft.net\framework\v2.0.50727\aspnet_isapi.dll)
• Ensure that 'check that file exists' is unchecked
• Click OK, OK, OK to close and apply changes

IIS7 Classic Mode / Integrated Pipeline mode

In IIS7 you can change the configuration in the web.config file, which saves having to mess about with the IIS user interface.  This is also very useful if your host doesn't give you direct access to your IIS interface.

What you need to do is specify a new handler for the .htm extension.  The entries below are separate : one for classic mode, one for integrated mode.  It's best just to enter both, in case you don't know if you're using classic or integrated, or if you decided to switch in the future.

<system.webserver>

<handlers>

<!-- classic mode .htm handler to make asp.net handle .htm requests -->

<add name="HtmlHandler-Classic" path="*.htm" verb="GET,HEAD,POST,DEBUG" modules="IsapiModule" scriptProcessor="C:\Windows\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll" requireAccess="Script" preCondition="classicMode,runtimeVersionv2.0,bitness32" />

<!-- integrated pipeline mode handler to make asp.net handle .htm requests -->
<add name="HtmlHandler-Integrated" path="*.htm" verb="GET,HEAD,POST,DEBUG" type="System.Web.UI.PageHandlerFactory" modules="ManagedPipelineHandler" requireAccess="Script" preCondition="integratedMode" />

</handlers>

</system.webserver>

These two entries inform IIS7 to run the related asp.net runtime when a .htm request is received.

4.  Configure ASP.NET to process .htm files

As previously mentioned, if you do have .htm files in your web application, then they are going to be processed by ASP.NET.  That's no problem, but you do need to let the ASP.NET runtime know about it. 

IIS6 / IIS7

First, tell ASP.NET how to handle .htm files by adding in a Http Handler

<system.web>
  <httpHandlers>    
    <add verb="*" path="*.htm" type="System.Web.UI.PageHandlerFactory" />
  </httpHandlers> 
</system.web>

Next, tell ASP.NET how to build a .htm file.  Note that nothing actually changes as there is no code in the file, but it still needs to be run through the build process.

<system.web>
  <compilation>    
    <buildProviders>
      <add extension=".htm" type="System.Web.Compilation.PageBuildProvider" />
    </buildProviders>
  </compilation> 
</system.web>

Remember that because the web.config file is an Xml file, all of this is case sensitive, so take care with all of your entries.

5.  Configure the Url Master software to stop ignoring .htm files.

This is done by expanding out the 'Advanced Regex Filters' section, and changing the value in the 'ignoreRegex'.  What you need to do is carefully remove the section relating to the .htm extension : it will look something like this: |\.htm$

Once this is done, the Url Master software will inspect all of the .htm requests for rewriting and allow it to perform a redirect if necessary.   Note that any time the Url Master module finds a physical file on the server relating to a request, it performs no rewriting.  In other words, if /myfiles/myfile.htm exists on the server, then the software knows that it's not a virtual Url, and therefore leaves it alone to continue processing.

Note : A virtual Url is a url that doesn't correspond to an actual file on your server.  A virtual Url is a 'made up' Url that doesn't work unless there is some software interpreting what the Url means.  That's the reason a 404 Resource Not Found error is quite common if your Url Rewriting isn't configured correctly.

6.  Add in your .htm redirects in the Url Master User Interface

To do this, go to the Admin->Page Urls page that is created when the Url Master software is installed.  In order to setup a redirect, you need to work backwards.  That is, you select the page you would like to redirect to, and enter the Url you'd like to redirect from.

Remember to click the 'apply changes' button when you're finished.

7. Test and Check your Results

There's two ways of testing your redirects.  The first is to go to the Friendly Url Settings page, and use the 'Test Url Rewriting' section.  Type in the full Url as you want redirected, and click the 'test' function.

The above example shows the test output for 'oldpage.htm', which redirects to the DNN page called 'New Page' at new-page.aspx.

Wrapping Up

These instructions actually contain the advice for another, related task.  You can run your DNN site on whatever extension you like : from .aspx, to .htm, even .php or .dnn!  There is no restriction on what the page extension is for your site.  If you want to run your entire DNN site on a different page extension, just change the page extension in the Friendly Url Settings page, and ensure all the above ASP.NET mapping is in place before you hit the 'Apply Changes' button.

I once read someone on an ASP.NET support forum lecturing another person for wanting to change away from .aspx : the lecture took the form of 'why would you want to even do that?'.  Well, there are many reasons not to run the .aspx extension for your DNN pages : backwards compatibility, obfuscation of technology, lots of reasons.

If you have other extensions that you need to redirect from, then you just follow the instructions as listed, replacing .htm with whatever extension you're working with.

Success Stories

If you've redirect an old site over to a new DNN site using the advice listed here, let us all know about it!  Just post your success stories in the comments.  I always get a kick out of seeing the code in action, solving what was once unsolvable problems!