Client-side redirection using HttpRedirection module

HttpRedirection module allows you to do client side redirection as per various configuration rules. There are not many changes from what IIS6 had but I thought it will be good to revisit its configuration and behavior in IIS7.

Redirection module is not part of default install. You can use OptionalFeatures in Vista or ServerManager in Longhorn Server to install it. This module does its work in MapRequestHandler stage of request pipeline and has its configuration in system.webServer/httpRedirect section. If system.webServer/httpRedirect has enabled set to true and destination non-blank, redirection module sends 3XX response to the client.

Configuration properties

Here is the list of configuration properties available to you to control the behavior of redirection module. All properties can be configured at URL level.

enabled – Tells the module if redirection is enabled or not. Only if enabled is set to true, redirection is attempted.

destination –If enabled is set to true, destination property is read to get redirect URL. You should use full path to destination URL and avoid use of relative paths. If destination URL starts with slash, we append hostname sent in the request. So if destination is set to “/path/file.htm”, redirect URL is changed to http://<hostname>/path/file.htm (assuming exactDestination is true). If destination includes full path, host header is not used and full path as configured is returned. So if destination is set to http://server/redirectpath/file.htm, we set location to this. If destination is set to blank, wildcard rules are evaluated.

wildcard rules collection – If section attribute destination is seen as blank (not set or set to blank at current or parent level), redirection module reads wildcard rules for requested URL. Redirection module compares requested URL against wildcard rules, picks the first rule which matches requested URL and uses destination as set in the corresponding wildcard rule. If destination is blank and there are no wildcard rules, redirection is not done.

exactDestination (true/false) -  This tells redirection module that the destination should be taken as exact URL and it should not append the original URL to it. If set to false, original URL is appended to the redirected URL. For example, if request is sent to /app/file.htm and destination is http://server/app2, redirect URL will be /app2/app/file.htm. You want to keep this true in most of the cases. Added URL is relative to the deepest file path where the httpRedirect section configuration is set.

childOnly (true/false) - This is a safeguard to prevent looping. This tells the redirection module that redirect URL is a subfolder of this folder and the current redirect rules applies to URLs under this folder only. Same can be done by setting enabled to false for subfolder.

httpResponseStatus – This property tells IIS what status code to send to the client. Possible values are Permanent (301), Found (302), Temporary (307). Default is set to Found. You can change this value at URL level.

Use of $S, $V, $P, $Q, $0-$9 in destination

$S - Part of the URL which remains after the redirect URL is substituted including forward slash. Depending on deepest path from where the configuration is picked, $S value will change. If the configuration is picked from current folder, $S is /filename. If configuration is picked from parent folder, $S will be /parentfolder/filename.

$V – Requested URL without servername starting with forward slash. This is very useful when redirecting to external website.

$P – querystring without starting ‘?’. This is helpful when you need to add some querystring variables and also pick variables from original request (see examples).

$Q – querystring including ‘?’. This is used when you need to send all querystring variables to the new URL without adding new ones. If there is no querystring in the original URL, $Q means blank string. So ‘?’ doesn’t get hardcoded in destination URL as in the case of $P.

$0-$9 – When specifying destination in wildcard rules, $0-$9 can be used to refer to various parts of the original URL which matched * (see examples).

!  is removed in IIS7. You can set enabled to false for the folder which you don’t want to redirect.

Note of caution: Destination and wildcard rules are just like other configuration properties and can be inherited from lower levels. So for a URL /app/vdir/folder/file.htm, configuration set for app is seen for vdir and folder as well. You need to be careful when you are setting the httpRedirect section. Redirection module checks deepest file path where httpRedirect configuration is set. If you set any httpRedirect property, it’s good to set all properties and not inherit values from parent. Let’s say if you set enabled to true but don’t set destination in web.config for vdir, you just changed the deepest path where the configuration is set to vdir. Now, if web.config for app had httpRedirect destination set, you inherit the value which might be using $S and you might end up with unexpected results. Also if you just set enabled to true and add some wildcard rules without setting section level destination to blank, it might get inherited from lower levels. In that case wildcard rules will never get evaluated. So it’s better to explicitly set section level destination property to blank when  adding wildcard rules. This ensures that values from parent folders is overridden and wildcard rules will be effective. Another thing you can do is clear the collection first so that you are sure that wildcard rules from parent folders are not effective.

Examples

Let’s configure httpRedirect section to set some common redirection rules.

1.  Redirect from vdir1 (including subfolders) to vdir2.
Configuration for vdir1 should be:
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”false” destination=”http://servername/<path>/vdir2$S” />

2.  Redirect from dir1 to a subfolder dir1\subdir (same filename and pass all querystring variables if any).
Config for dir1 should be:
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”true” destination=”http://servername/<path>/dir1/subdir$S$Q” />

3.  Redirect to another server in some folder and send requested URL as querystring variable along with other variables.
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”false” destination=”http://otherserver/app/folder$S?originalURL=$V&$P” />

4.  Redirect http requests as https.
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”false” destination=”https://server$V” />

5.  Redirect asp requests to one folder and aspx requests to another.
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”true” destination=””>
    <clear/>
    <add wildcard=”*.asp” destination=”http://server/folder1$0.asp” />
    <add wildcard=”*.aspx” destination=”http://server/folder2$0.aspx” />
</httpRedirect>

6.  Send .htm requests to .aspx requests in the same folder.
<httpRedirect enabled=”true” exactDestination=”true” childOnly=”true” destination=””>
    <clear/>
    <add wildcard=”*.htm” destination=”http://server/<path>$0.aspx” />
</httpRedirect>
If you want to redirect only one file, you should set httpRedirect section under location tag for that file only so that redirect module doesn’t try to build destination or match wildcard rules for rest of the files.

IIS Manager in Vista doesn’t provide functionality to edit httpRedirect section. In LH server, IIS Manager does allow you to set section level properties but not wildcard rules. You can either add/remove rules directly into the configuration or use appcmd. Command to add a wildcard rule will look like “appcmd set config /section:httpRedirect /+[wildcard=’*.htm’,destination=’$0.aspx’]”.

-Kanwal-