HttpRedirect
The HttpRedirect property specifies the directory or URL to which a client is redirected when attempting to access a specific resource (a virtual directory, a Web directory, or a file). There are two general forms that the value for this property can take, each with specific syntax, described in the Remarks section below.
For information about setting this property using IIS Manager, see Configuring Properties in the IIS User Interface. For information about setting this property programmatically from ASP, COM, ISAPI or administration scripts, see Redirecting Requests in IIS.
Setting HttpRedirect at the site or service level has no affect.
.gif "Important note") Important Note: |
|---|
To remove a redirect, the HttpRedirect metabase property must be deleted. IIS returns a "The page cannot be displayed" error if the HttpRedirect metabase property is set to an empty string. |
Schema Attributes
Attribute name |
Value |
|---|---|
STRING |
|
STRING_METADATA |
|
null |
|
Not specified. |
|
Not specified |
|
Not specified |
|
6011 |
|
MD_HTTP_REDIRECT |
|
INHERIT |
|
IIS_MD_UT_FILE |
Configurable Locations
You can configure this property at the following locations in the IIS metabase.
Metabase path |
IIS Admin object type |
|---|---|
/LM/W3SVC/n/ROOT/file_name /LM/W3SVC/n/ROOT/virtual_directory_name/file_name |
IIsWebFile |
/LM/W3SVC/n/ROOT/physical_directory_name /LM/W3SVC/n/virtual_directory_name/physical_directory_name |
IIsWebDirectory |
/LM/W3SVC/n/ROOT /LM/W3SVC/n/ROOT/virtual_directory_name |
IIsWebVirtualDir |
Flags
There are no flags for this property.
Remarks
Configure IIS to redirect client requests if your content is under construction or has changed identity. This ensures that client requests always resolve to an available page. You can redirect client requests from a virtual directory, a Web directory, or a file, to a resource on the same Web server or to a different URL.
Redirection can take one of the two following forms, both of which set the HttpRedirect metabase property.
Redirection to a URL
A simple redirection string uses the following format:
http://DestinationURL[, Flags]
Where DestinationURL can optionally include the following redirect variables to pass portions of the original URL with the destination URL. More than one variable is allowed.
URLs can be used to configure redirection programmatically and in the IIS user interface.
Variable |
Description |
Example |
|---|---|---|
$S |
Passes the suffix of the requested URL to the new URL. The suffix is the portion of the original URL that remains after the redirected URL is substituted. If the EXACT_DESTINATIONFlag is not set, the resulting destination URL will have the name of the requested file appended as a folder name, as well as the file name itself. |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured to be redirected to the following exact URL: http://fabrikam/NewScripts$S then a new request for the following URL: http://fabrikam/Scripts/Program.exe Would be automatically redirected to the following URL: http://fabrikam/NewScripts/Program.exe |
$P |
Passes parameters (such as querystring parameters) in the original URL to the new URL, without the question mark (?). |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured to be redirected to the following URL: http://fabrikam/NewScripts$P then a new request for the following URL: http://fabrikam/Scripts/File.asp?var1=5&var2=6 Would be automatically redirected to the following URL: http://fabrikam/NewScriptsvar1=5&var2=6 |
$Q |
Passes parameters (such as querystring parameters) in the original URL to the new URL, including the question mark (?). |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured to be redirected to the following exact URL: http://fabrikam/NewScripts$S$Q then a new request for the following URL: http://fabrikam/Scripts/File.asp?var1=5&var2=6 Would be automatically redirected to the following URL: http://fabrikam/NewScripts/File.asp?var1=5&var2=6 |
$V |
Passes the requested URL, without the server name and without any parameters. To include parameters, use the $P or $Q variable with the $V variable. If the EXACT_DESTINATIONFlag is not set, the resulting destination URL will have the name of the requested file appended as a folder name, as well as the file name itself. |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured to be redirected to the following exact URL: http://contoso$V then a new request for the following URL: http://fabrikam/Scripts/File.asp Would be automatically redirected to the following URL: http://contoso/Scripts/File.asp |
Redirection Using Wildcards
A more complex redirection string uses one of the the following formats:
*; Wildcard1; Destination1[; Wildcard2; Destination2][, Flags]
*; !
Where WildcardN can include a star (*) character to match any number of characters in the original URL and pass them to DestinationN by using the $0 through $9 variables defined in the following table.
Wildcards can only be used to configure redirection programmatically; not in the IIS user interface.
Variable |
Description |
Example |
|---|---|---|
$0 through $9 |
Passes the portion of the requested URL that matches the indicated wildcard character. Wildcards must start at $0 for each Wildcard; Destination set. The EXACT_DESTINATION flag must be appended to the redirection string. |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured with the following redirection string: *; /Scripts/*_in.asp; /NewScripts/$0.dll; /Scripts/*_out.asp; http://contoso/NewScripts/$0.dll then a new request for the following URLs: http://fabrikam/Scripts/data_in.asp http://fabrikam/Scripts/data_out.asp Would be automatically redirected to the following respective URLs: http://fabrikam/NewScripts/data.dll http://contoso/NewScripts/data.dll |
! |
Does not allow a redirect. This variable is useful to exempt files or subdirectories from redirection when a parent directory is configured to be redirected. |
If the virtual directory that is mapped to the following Web site: http://fabrikam/Scripts is configured to be redirected, but the following Web site: http://fabrikam/Scripts/Commerce/Accounts needs to be exempt, then programmatically set the redirection string for the exempted folder to the following: *;! |
Flags Used with Either Format
The following flags are used to augment redirect strings of either format. More than one flag is allowed. Flags can be appended programmatically to the redirection string in HttpRedirect, or they can be configured by selecting checkboxes in the IIS user interface.
Flag |
User interface checkbox |
Description |
|---|---|---|
EXACT_DESTINATION |
The exact URL entered above |
Indicates that the value provided for Destination should be considered an absolute target location. |
CHILD_ONLY |
A directory below this one |
Alerts IIS that redirection should occur only once because the destination is in a subdirectory of the original URL. This flag avoids loops. Also, this flag instructs IIS only to redirect requests if they are to subfolders or files of the original URL. |
PERMANENT |
A permanent redirection for this resource |
Indicates that this redirection is permanent for this resource. |
TEMPORARY |
Deselect the A permanent redirection for this resource checkbox |
Indicates that this redirection is temporary for this resource. |
Requirements
Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0.
Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0.
Product: IIS