HTTP Redirects <httpRedirect>
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.contoso.com/app_v1.0/
) to the new applications location (for example, http://www.contoso.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 10.0 | An additional HTTP response status was added to the <httpRedirect> element in IIS 10.0. |
IIS 8.5 | The <httpRedirect> element was not modified in IIS 8.5. |
IIS 8.0 | The <httpRedirect> element was not modified in IIS 8.0. |
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 and later. To install it, use the following steps.
Windows Server 2012 or Windows Server 2012 R2
- On the taskbar, click Server Manager.
- In Server Manager, click the Manage menu, and then click Add Roles and Features.
- In the Add Roles and Features wizard, click Next. Select the installation type and click Next. Select the destination server and click Next.
- On the Server Roles page, expand Web Server (IIS), expand Web Server, expand Common HTTP Features, and then select HTTP Redirection. Click Next.
. - On the Select features page, click Next.
- On the Confirm installation selections page, click Install.
- On the Results page, click Close.
Windows 8 or Windows 8.1
- On the Start screen, move the pointer all the way to the lower left corner, right-click the Start button, and then click Control Panel.
- In Control Panel, click Programs and Features, and then click Turn Windows features on or off.
- Expand Internet Information Services, expand World Wide Web Services, expand Common HTTP Features, and then select HTTP Redirection.
- Click OK.
- Click Close.
Windows Server 2008 or Windows Server 2008 R2
- On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
- In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
- In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
- On the Select Role Services page of the Add Role Services Wizard, expand Common Http Features, select HTTP Redirection, and then click Next.
- On the Confirm Installation Selections page, click Install.
- On the Results page, click Close.
Windows Vista or Windows 7
- On the taskbar, click Start, and then click Control Panel.
- In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
- Expand Internet Information Services, then World Wide Web Services, then Common Http Features.
- 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
Open Internet Information Services (IIS) Manager:
If you are using Windows Server 2012 or Windows Server 2012 R2:
- On the taskbar, click Server Manager, click Tools, and then click Internet Information Services (IIS) Manager.
If you are using Windows 8 or Windows 8.1:
- Hold down the Windows key, press the letter X, and then click Control Panel.
- Click Administrative Tools, and then double-click 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.
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.
In the HTTP Redirect pane, check the box to redirect requests and enter the destination URL.
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 options:
- 301 Permanent
- 302 Found
- 307 Temporary
- 308 Permanent Redirect
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
- HTTP 1.1 308 Redirected Permanently
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://marketing.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 .
|
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. |
Configuration Sample
The following default <httpRedirect>
element is configured in the root ApplicationHost.config file in IIS 7 when the HTTP Redirection role service is installed. This configuration section inherits the default configuration settings unless you use the <clear>
element.
<system.webServer>
<httpRedirect enabled="false" />
</system.webServer>
The following configuration sample enables redirection and configures the destination URL to which clients are redirected.
<system.webServer>
<httpRedirect enabled="true" destination="http://www.contoso.com/" />
</system.webServer>
The following configuration sample adds a wildcard redirection entry that redirects all requests for PHP files to the home page of your Web site.
Note
This example is useful if you have removed all ASP-based applications from your Web site and you wanted client requests for the old applications to be redirected to the root of your Web site rather than receiving an HTTP 404 Not Found response.
<configuration>
<system.webServer>
<httpRedirect enabled="true" exactDestination="true" httpResponseStatus="Found">
<add wildcard="*.php" destination="/default.htm" />
</httpRedirect>
</system.webServer>
</configuration>
Sample Code
The following code samples configure the Default Web Site to redirect all requests to http://www.contoso.com
using an HTTP 302 status code.
AppCmd.exe
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /enabled:"True"
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /destination:"http://www.contoso.com"
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /exactDestination:"False"
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /httpResponseStatus:"Found"
C#
using System;
using System.Text;
using Microsoft.Web.Administration;
internal static class Sample
{
private static void Main()
{
using (ServerManager serverManager = new ServerManager())
{
Configuration config = serverManager.GetWebConfiguration("Default Web Site");
ConfigurationSection httpRedirectSection = config.GetSection("system.webServer/httpRedirect");
httpRedirectSection["enabled"] = true;
httpRedirectSection["destination"] = @"http://www.contoso.com";
httpRedirectSection["exactDestination"] = false;
httpRedirectSection["httpResponseStatus"] = @"Found";
serverManager.CommitChanges();
}
}
}
VB.NET
Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
Sub Main()
Dim serverManager As ServerManager = New ServerManager
Dim config As Configuration = serverManager.GetWebConfiguration("Default Web Site")
Dim httpRedirectSection As ConfigurationSection = config.GetSection("system.webServer/httpRedirect")
httpRedirectSection("enabled") = True
httpRedirectSection("destination") = "http://www.contoso.com"
httpRedirectSection("exactDestination") = False
httpRedirectSection("httpResponseStatus") = "Found"
serverManager.CommitChanges()
End Sub
End Module
JavaScript
var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site";
var httpRedirectSection = adminManager.GetAdminSection("system.webServer/httpRedirect", "MACHINE/WEBROOT/APPHOST/Default Web Site");
httpRedirectSection.Properties.Item("enabled").Value = true;
httpRedirectSection.Properties.Item("destination").Value = "http://www.contoso.com";
httpRedirectSection.Properties.Item("exactDestination").Value = false;
httpRedirectSection.Properties.Item("httpResponseStatus").Value = "Found";
adminManager.CommitChanges();
VBScript
Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site"
Set httpRedirectSection = adminManager.GetAdminSection("system.webServer/httpRedirect", "MACHINE/WEBROOT/APPHOST/Default Web Site")
httpRedirectSection.Properties.Item("enabled").Value = True
httpRedirectSection.Properties.Item("destination").Value = "http://www.contoso.com"
httpRedirectSection.Properties.Item("exactDestination").Value = False
httpRedirectSection.Properties.Item("httpResponseStatus").Value = "Found"
adminManager.CommitChanges()
The following code samples adds a wildcard redirection entry that redirects all requests for ASP files to the home page of your Web site.
Note
This example is useful if you have removed all ASP-based applications from your Web site and you wanted client requests for the old applications to be redirected to the root of your Web site rather than receiving an HTTP 404 Not Found response.
AppCmd.exe
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /enabled:"True" /exactDestination:"True" /httpResponseStatus:"Found"
appcmd.exe set config "Default Web Site" -section:system.webServer/httpRedirect /+"[wildcard='*.asp',destination='/default.htm']"
C#
using System;
using System.Text;
using Microsoft.Web.Administration;
internal static class Sample
{
private static void Main()
{
using(ServerManager serverManager = new ServerManager()) {
Configuration config = serverManager.GetWebConfiguration("Default Web Site");
ConfigurationSection httpRedirectSection = config.GetSection("system.webServer/httpRedirect");
httpRedirectSection["enabled"] = true;
httpRedirectSection["exactDestination"] = true;
httpRedirectSection["httpResponseStatus"] = @"Found";
ConfigurationElementCollection httpRedirectCollection = httpRedirectSection.GetCollection();
ConfigurationElement addElement = httpRedirectCollection.CreateElement("add");
addElement["wildcard"] = @"*.asp";
addElement["destination"] = @"/default.htm";
httpRedirectCollection.Add(addElement);
serverManager.CommitChanges();
}
}
}
VB.NET
Imports System
Imports System.Text
Imports Microsoft.Web.Administration
Module Sample
Sub Main()
Dim serverManager As ServerManager = New ServerManager
Dim config As Configuration = serverManager.GetWebConfiguration("Default Web Site")
Dim httpRedirectSection As ConfigurationSection = config.GetSection("system.webServer/httpRedirect")
httpRedirectSection("enabled") = True
httpRedirectSection("exactDestination") = True
httpRedirectSection("httpResponseStatus") = "Found"
Dim httpRedirectCollection As ConfigurationElementCollection = httpRedirectSection.GetCollection
Dim addElement As ConfigurationElement = httpRedirectCollection.CreateElement("add")
addElement("wildcard") = "*.asp"
addElement("destination") = "/default.htm"
httpRedirectCollection.Add(addElement)
serverManager.CommitChanges()
End Sub
End Module
JavaScript
var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site";
var httpRedirectSection = adminManager.GetAdminSection("system.webServer/httpRedirect", "MACHINE/WEBROOT/APPHOST/Default Web Site");
httpRedirectSection.Properties.Item("enabled").Value = true;
httpRedirectSection.Properties.Item("exactDestination").Value = true;
httpRedirectSection.Properties.Item("httpResponseStatus").Value = "Found";
var httpRedirectCollection = httpRedirectSection.Collection;
var addElement = httpRedirectCollection.CreateNewElement("add");
addElement.Properties.Item("wildcard").Value = "*.asp";
addElement.Properties.Item("destination").Value = "/default.htm";
httpRedirectCollection.AddElement(addElement);
adminManager.CommitChanges();
VBScript
Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Default Web Site"
Set httpRedirectSection = adminManager.GetAdminSection("system.webServer/httpRedirect", "MACHINE/WEBROOT/APPHOST/Default Web Site")
httpRedirectSection.Properties.Item("enabled").Value = True
httpRedirectSection.Properties.Item("exactDestination").Value = True
httpRedirectSection.Properties.Item("httpResponseStatus").Value = "Found"
Set httpRedirectCollection = httpRedirectSection.Collection
Set addElement = httpRedirectCollection.CreateNewElement("add")
addElement.Properties.Item("wildcard").Value = "*.asp"
addElement.Properties.Item("destination").Value = "/default.htm"
httpRedirectCollection.AddElement(addElement)
adminManager.CommitChanges()