Http redirect in IIS

The <httpRedirect> element configures settings for Internet Information Services (IIS) 7 that redirect client requests to a new location.

There are several reasons why you might want to redirect clients to a new location. For example, if your company is migrating to a new Web site, you could redirect all requests from the old Web site to the new Web site. Likewise, if you have deployed a new application on a Web server, you could redirect all requests for the old application's URL namespace (for example, http://www.consoto.com/app_v1.0/) to the new applications location (for example, http://www.consoto.com/app_v2.0/).

In the simplest configuration, you need only set the enabled and destination attributes of the <httpRedirect> element in order to redirect clients to a new location. However, additional elements like the exactDestination and httpResponseStatus attributes allow you to configure the end-user experience of the redirection by respectively specifying whether IIS 7 will return the destination URL exactly as entered and which HTTP response code to return to the Web client.

Compatibility

Version	Notes
IIS 7.5	The <httpRedirect> element was not modified in IIS 7.5.
IIS 7.0	The <httpRedirect> element was introduced in IIS 7.0.
IIS 6.0	The <httpRedirect> element replaces the IIS 6.0 HttpRedirect metabase property.

Setup

HTTP Redirection is not available on the default installation of IIS 7. To install it, use the following steps.

WINDOWS SERVER 2008 OR WINDOWS SERVER 2008 R2

1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
4. On the Select Role Services page of the Add Role Services Wizard, expand Common Http Features, select HTTP Redirection, and then click Next.
   
5. On the Confirm Installation Selections page, click Install.
6. On the Results page, click Close.

WINDOWS VISTA OR WINDOWS 7

1. On the taskbar, click Start, and then click Control Panel.
2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
3. Expand Internet Information Services, then World Wide Web Services, then Common Http Features.
4. Select HTTP Redirection, and then click OK.
   

How To

There is no user interface for adding wildcard HTTP redirects for IIS 7. For examples of how to add <add> elements to the<httpRedirect> element programmatically, see the Code Samples section of this document.

HOW TO ADD AN HTTP REDIRECT RULE TO A WEB SITE OR APPLICATION

1. Open Internet Information Services (IIS) Manager:
   • If you are using Windows Server 2008 or Windows Server 2008 R2:
     • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.
   • If you are using Windows Vista or Windows 7:
     • On the taskbar, click Start, and then click Control Panel.
     • Double-click Administrative Tools, and then double-click Internet Information Services (IIS) Manager.
2. In the Connections pane, expand the server name, expand Sites, and then navigate to the Web site or application that you want to configure custom error pages for.
3. In the Home pane, double-click HTTP Redirect.
   
4. In the HTTP Redirect pane, check the box to redirect requests and enter the destination URL.
   
5. You can optionally specify any of the following options:
   • Configure the redirection destination to be the exact destination as entered.
   • Configure the redirection destination to be limited to the destination URL's root folder, not subfolders.
   • Configure the HTTP status code, which can be one of these three options:
     • 301 Permanent
     • 302 Found
     • 307 Temporary
     Note: IIS 7 will respectively return the following actual HTTP response statuses for each of the above options:
     • HTTP/1.1 301 Moved Permanently
     • HTTP/1.1 302 Redirect
     • HTTP/1.1 307 Redirect
6. When you have finished all the above changes, click Apply in the Tasks pane.

Configuration

ATTRIBUTES

Attribute	Description
childOnly	Optional Boolean attribute. Specifies whether the destination value should be added to the beginning of the file name that contains the request to be redirected. For example, if childOnly were set to true and the destination value were configured to be http://marking.contoso.com/, a request for http://contoso.com/default.htm would be redirected to http://marketing.contoso.com/default.htm. The default value is false.
destination	Optional string attribute. Specifies a URL or virtual path to which to redirect the client.
enabled	Optional Boolean attribute. Specifies whether redirection is enabled (true) or disabled (false). The default value is false.
exactDestination	Optional Boolean attribute. Specifies that the destination value should be considered an absolute target location, not a relative location. The default value is false.
httpResponseStatus	Optional enum attribute. Specifies type of redirection. The httpResponseStatus attribute can be one of the following possible values. The default is Found. Value Description Found Returns a 302 status code, which tells the client to issue a new request to the location specified in the destination attribute. The numeric value is 302. Permanent Returns a 301 status code, which informs the client that the location for the requested resource has permanently changed. The numeric value is 301. Temporary Returns a 307 status code, which prevents the client from losing data when the browser issues an HTTP POST request. The numeric value is 307.

CHILD ELEMENTS

Element	Description
add	Optional element. Adds a wildcard redirection rule to the collection of redirection rules.
clear	Optional element. Removes all references to wildcard redirection rules from the collection of redirection rules.
remove	Optional element. Removes a reference to a wildcard redirection rule from the collection of redirection rules.