HttpRedirect

IIS 6.0

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.

ms525695.alert_caution(en-us,VS.90).gifImportant 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.

Attribute name

Value

ADSI/WMI Data Type

STRING

ABO Data Type

STRING_METADATA

Schema Default

null

Internal Default

Not specified.

Upper Bound

Not specified

Lower Bound

Not specified

Internal ID

6011

Friendly ID

MD_HTTP_REDIRECT

Property Attributes

INHERIT

User Type

IIS_MD_UT_FILE

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

There are no flags for this property.

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.

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

Show: