IIS-URL重写模块配置参考

本文提供了URL重写模块的概述，并解释了该模块使用的配置概念。

功能概述
URL重写模块将请求URL重写为显示给用户或Web应用程序的简单，用户友好和搜索引擎友好的地址。URL重写使用定义的规则进行评估，然后将请求URL映射到规则中定义的地址，然后再由IIS Web服务器对其进行处理。您可以定义包括正则表达式和通配符的URL重写逻辑，并且可以基于请求URL，HTTP标头和服务器变量来应用规则。该模块的主要目的是将请求URL重写为更友好的URL，但是您也可以使用该模块来定义执行重定向，发送自定义响应或中止请求的规则。

重写规则概述
重写规则定义了将请求URL与之进行比较或匹配的逻辑，以及在比较成功后该怎么做的逻辑。

重写规则包括以下部分：

模式 –规则模式用于指定用于匹配URL字符串的正则表达式或通配符模式。
条件 –可选条件集合用于指定URL字符串与规则模式匹配时要执行的其他逻辑操作。在这些条件下，您可以检查HTTP标头或服务器变量的某些值，或验证请求的URL是否对应于物理文件系统上的文件或目录。
动作 –动作用于指定如果URL字符串与规则模式匹配且所有规则条件均得到满足，该怎么办。

重写规则范围
可以在两个不同的集合中定义重写规则：

<globalRules>–此集合中的规则只能在服务器级别上定义。全局规则用于定义服务器范围的URL重写逻辑。这些规则在ApplicationHost.config文件中定义，并且不能在任何较低的配置级别上覆盖或禁用它们。全局规则始终在绝对URL的路径上运行（即，所请求的URI不带服务器名称）。这些规则在IIS请求处理管道（PreBeginRequest事件）的早期进行评估。
<rules>–此集合中的规则称为分布式规则，可以在配置层次结构的任何级别上定义它们。分布式规则用于定义特定于特定配置范围的URL重写逻辑。可以使用Web.config文件或<location>ApplicationHost.config或Web.config文件中的标记在任何配置级别上添加这种类型的规则。相对于定义它们的Web.config文件的位置，分布式规则在URL路径上运行。如果在<location>标签内部定义了分布式规则，则它们将在URL路径（相对于为该<location>标签指定的路径）上运行。这些规则在IIS管道中的BeginRequest事件上进行评估。

规则评估
IIS中的每个配置级别都可以定义零个或多个重写规则。规则以指定顺序进行评估。URL重写模块通过使用以下算法来处理规则集：

首先，URL与规则模式匹配。如果不匹配，URL重写模块将立即停止处理该规则，并继续执行下一个规则。
如果模式匹配且该规则没有条件，则URL重写模块将执行为此规则指定的操作，然后继续执行下一个规则，在该规则中它将替换的URL用作该规则的输入。
如果模式匹配且规则存在条件，则URL重写模块将评估条件。如果评估成功，则执行指定的规则操作，然后将重写的URL用作后续规则的输入。
规则可能已启用StopProcessing标志。当执行规则操作（即匹配规则）并且打开此标志时，这意味着将不再处理后续的规则，并且该请求将被传递到IIS请求管道。默认情况下，此标志是关闭的。

规则继承
如果在多个配置级别上定义了规则，则URL重写模块将按以下顺序评估规则：

评估所有全局规则。
评估一个规则集，其中包括来自父配置级别的分布式规则以及来自当前配置级别的规则。评估以父子顺序执行，这意味着首先评估父规则，最后评估在最后一个子级别定义的规则。

保留原始URL
URL重写模块在以下服务器变量中保留了原始请求的URL路径：

HTTP_X_ORIGINAL_URL –此服务器变量包含解码格式的原始URL；
UNENCODED_URL –此服务器变量包含与Web客户端完全相同的原始URL，并保留了所有原始编码。

通过重写规则访问URL部件
重要的是要了解如何从重写规则访问URL字符串的某些部分。

对于以下形式的HTTP URL：http（s）：// <主机>：<端口> / <路径>？<查询字符串>

<path>与规则的模式匹配。
<querystring>在名为QUERY_STRING的服务器变量中可用，并且可以使用规则中的条件进行访问。
<host>在服务器变量HTTP_HOST中可用，并且可以通过使用规则中的条件进行访问。
<port>在服务器变量SERVER_PORT中可用，并且可以使用规则中的条件进行访问。
服务器变量SERVER_PORT_SECURE和HTTPS可用于确定是否使用了安全连接。可以通过使用规则中的条件来访问这些服务器变量。
服务器变量REQUEST_URI可用于访问整个请求的URL路径，包括查询字符串。
例如，如果请求此URL http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3：，并且在网站级别定义了重写规则，则：

规则模式将URL字符串content/default.aspx作为输入。
QUERY_STRING服务器变量包含tabid=2&subtabid=3。
HTTP_HOST服务器变量包含www.mysite.com。
SERVER_PORT服务器变量包含80。
服务器变量SERVER_PORT_SECURE包含，0而HTTPS包含OFF。
REQUEST_URI服务器变量包含/content/default.aspx?tabid=2&subtabid=3。
PATH_INFO服务器变量包含/content/default.aspx。
请注意，传递给分布式规则的输入URL字符串始终与定义规则的Web.config文件的位置有关。例如，如果请求http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3，并且在/ content目录中定义了重写规则，则该规则将获取此URL字符串default.aspx作为输入。

重写规则配置

规则模式
重写规则模式用于指定与当前URL路径进行比较的模式。在这种情况下，当前是指应用规则时URL路径的值。如果当前规则之前有任何规则，则它们可能已经与原始请求的URL匹配并进行了修改。根据模式评估的URL字符串不包括查询字符串。要将查询字符串包括在规则评估中，可以在规则的条件中使用QUERY_STRING服务器变量。有关更多信息，请参阅“在重写规则中使用服务器变量”。

在重写规则的<match>元素内指定了模式。

规则模式语法
可以使用规则的patternSyntax属性指定规则模式语法。可以将此属性设置为以下选项之一：

ECMAScript – Perl兼容（符合ECMAScript标准）正则表达式语法。这是任何规则的默认选项。这是模式格式的示例：“ ^（[_ 0-9a-zA-Z-]-//）？（wp-。*）”

通配符 – IIS HTTP重定向模块中使用的通配符语法。以下是这种格式的示例：“ / Scripts / * _ in。???”，其中星号（“ *”）表示“匹配任意数量的任何字符并在向后引用中捕获它们”和“ ？表示完全匹配一个字符（不创建反向引用）。

patternSyntax属性的范围是每个规则的范围，这意味着它适用于当前规则的模式以及该规则条件内使用的所有模式。

规则模式属性
可以通过使用<match>元素的negate属性来否定模式。使用此属性时，仅当当前URL 与指定的模式不匹配时，才执行规则操作。

默认情况下，使用不区分大小写的模式匹配。要启用区分大小写，可以使用规则的<match>元素的ignoreCase属性。

规则条件
规则条件允许为规则评估定义其他逻辑，这些逻辑可以基于输入，而不仅仅是当前URL字符串。任何规则都可以具有零个或多个条件。规则模式匹配成功后，将评估规则条件。

条件是在重写条件的<conditions>集合中定义的。该集合具有一个称为logicalGrouping的属性，该属性控制如何评估条件。如果规则有条件，则仅在匹配规则模式且满足以下条件时才执行规则操作：

前提是使用的是logicalGrouping =“ MatchAll”，所有条件均被评估为true 。
前提条件是至少有一个条件为true，前提是使用了logicalGrouping =“ MatchAny”。
通过指定以下属性来定义条件：

输入字串
比赛类型
条件输入指定将哪个项目用作条件评估的输入。条件输入是一个任意字符串，可以包括服务器变量和对先前条件模式和/或规则模式的反向引用。

匹配类型可以是以下三个选项之一：

IsFile –此匹配类型用于确定输入字符串是否包含文件系统上文件的物理路径。如果未指定条件输入字符串，则URL重写模块会将请求文件的物理路径用作条件输入的默认值。此匹配类型只能用于分布式规则。
IsDirectory –此匹配类型用于确定输入字符串是否包含文件系统上目录的物理路径。如果未指定条件输入字符串，则URL重写模块会将请求文件的物理路径用作条件输入的默认值。此匹配类型只能用于分布式规则。
模式 -此匹配类型用于表示条件，其中任意输入字符串与正则表达式模式匹配。可以使用正则表达式语法或通配符语法来指定条件模式。条件中使用的模式类型取决于为此条件所属的规则定义的patternSyntax标志的值。此条件类型具有控制模式匹配的两个相关属性：

pattern –使用此属性可以指定实际的模式。
ignoreCase –使用此属性来控制条件的模式匹配是区分大小写还是不区分大小写。
另外，可以通过使用negate属性来否定条件评估的结果。这可以用于指定一个条件，该条件检查所请求的URL是否不是文件，如以下示例所示：

XML格式

复制
<add input="{REQUEST_FILENAME}" matchType="isFile" negate="true">

规则动作
当当前URL匹配规则模式并且条件评估成功时（取决于规则配置，所有条件匹配还是任何一个或多个条件匹配），将执行重写规则操作。有几种类型的操作可用，<action>配置元素的type属性可用于指定规则执行的操作。以下各节描述了不同的操作类型以及与特定操作类型相关的配置选项。

重写动作
一个重写的动作替换当前URL字符串替换字符串。替换字符串必须始终指定URL路径（例如contoso / test / default.aspx）。请注意，C:\inetpub\wwwrootIIS不支持包含文件系统上的物理路径的替换（例如，）。

一个重写的动作有以下配置选项：

url –这是重写当前URL时要使用的替换字符串。替换URL是一个字符串值，可以包含以下内容：

对条件和规则模式的反向引用。（有关更多信息，请参见有关如何使用反向引用的部分。）
服务器变量。（有关更多信息，请参见有关如何使用服务器变量的部分。）
appendQueryString –指定在替换过程中是否保留当前URL的查询字符串。默认情况下，如果未指定appendQueryString标志的值，则假定它为TRUE。这意味着来自原始URL的查询字符串将附加到替代URL。

重定向动作
一个重定向操作指示的URL重写模块发送重定向响应返回给客户端。可以将重定向状态代码（3xx）指定为该操作的参数。响应的“ 位置”字段包含规则中指定的替换字符串。

可以使用以下格式之一指定重定向规则的替换URL：

相对URL路径– contoso / test / default.aspx
绝对URI – https://example.com/contoso/test/default.aspx
使用重定向操作意味着执行重定向后，不会为当前URL评估任何后续规则。

一个重定向操作具有以下配置选项：

url –使用替代字符串作为重定向URL。替换URL是可以包括以下内容的字符串：

对条件和规则模式的反向引用。（有关更多信息，请参见有关如何使用反向引用的部分。）
服务器变量。（有关更多信息，请参见有关如何使用服务器变量的部分。）
appendQueryString –指定在替换期间是否应保留当前URL的查询字符串。默认情况下，如果未指定AppendQueryString标志，则假定它为TRUE。这意味着来自原始URL的查询字符串将附加到替代URL。
redirectType –指定重定向期间要使用的状态代码：

301 –永久
302 –找到
303 –其他
307 –临时

CustomResponse操作
甲CustomResponse动作通过使用用户指定的状态码，子码，和原因导致URL重写模块向HTTP客户端响应。使用CustomResponse操作意味着执行此操作后，不会为当前URL评估任何后续规则。

CustomResponse操作具有以下配置选项：

statusCode –指定用于响应客户端的状态码。
subStatusCode –指定用于响应客户端的子状态代码。
statusReason –指定要与状态代码一起使用的原因短语。
statusDescription –指定要放入响应正文中的一行描述。

AbortRequest操作
一个AbortRequest动作导致URL重写模块放弃对当前请求的HTTP连接。该动作没有任何参数。使用此操作意味着执行此操作后，不会为当前URL评估任何后续规则。

无动作
一个无动作用于指定不执行任何操作。

在重写规则中使用服务器变量
服务器变量提供有关当前HTTP请求的其他信息。您可以使用此信息来做出重写决定或编写重写的URL。可以在重写规则中的以下位置引用服务器变量：

在条件输入字符串中
在规则替换字符串中，特别是：

重写和重定向操作的url属性
状态行和responseLine一个的CustomResponse行动
可以使用{VARIABLE_NAME}语法引用服务器变量。例如，以下条件使用QUERY_STRING服务器变量：

XML格式

复制
<add input="{QUERY_STRING}" pattern="id=([0-9]+)" />
服务器变量还可以用于从当前请求访问HTTP标头。当前请求提供的任何HTTP标头都表示为服务器变量，该服务器变量具有根据以下命名约定生成的名称：

HTTP标头名称中的所有破折号（“-”）都将转换为下划线符号（“ _”）。
HTTP标头名称中的所有字母都将转换为大写字母。
标头名称中将添加“ HTTP_”前缀。
例如，为了从重写规则访问HTTP标头“用户代理”，可以使用{HTTP_USER_AGENT}服务器变量。

在重写规则中使用反向引用
规则或条件输入的一部分可以在反向引用中捕获。然后，可以将它们用于在规则操作内构造替换URL或为规则条件构造输入字符串。

反向引用的生成方式不同，具体取决于规则使用哪种模式语法。使用ECMAScript模式语法时，可以通过在模式中必须捕获反向引用的部分周围加上括号来创建反向引用。例如，图案。（[0-9] +）/（[AZ] +）的html将捕获07和物品从该请求的URL反向引用：07 / article.html。当使用“通配符”模式语法时，在模式中使用星号（*）时始终创建向后引用。当“？”时，不会创建反向引用。在模式中使用。例如，模式* / *。html将捕获contoso并进行测试在此请求的URL的反向引用中：contoso / test.html。

不管使用哪种模式语法捕获反向引用，其用法都是相同的。可以在重写规则中的以下位置使用反向引用：

条件输入字符串
在规则操作中，特别是：

重写和重定向操作的url属性
状态行和responseLine一个的CustomResponse行动
在重写映射的关键参数中
对条件模式的后向引用由{C：N}标识，其中N为0到9。对规则模式的后向引用由{R：N}标识，其中N为0到9。请注意，对于两种类型的向后引用{R：0}和{C：0}将包含匹配的字符串。

例如，在这种模式下：

安慰

复制
^(www\.)(.*)$
对于字符串：www.foo.com反向引用的索引如下：

JSON格式

复制
{C:0} - www.foo.com
{C:1} - www.
{C:2} - foo.com
在规则操作中，可以使用对规则模式和该规则的最后匹配条件的反向引用。在条件输入字符串中，您可以使用对规则模式和先前匹配条件的反向引用。

以下规则示例演示了如何创建和引用反向引用：

XML格式

复制
<rule name="Rewrite subdomain">
<match url="^(.+)" /> <!-- rule back-reference is captured here -->
<conditions>
<add input="{HTTP_HOST}" type="Pattern" pattern="^([^.]+)\.mysite\.com$" /> <!-- condition back-reference is captured here -->
</conditions>
<action type="Rewrite" url="{C:1}/{R:1}" /> <!-- rewrite action uses back-references to condition and to rule when rewriting the url -->
</rule>

与IIS输出缓存的交互
URL重写模块控制IIS输出缓存行为，以便：

最佳利用响应的内核模式和用户模式输出缓存来重写URL，从而提高使用URL重写模块的Web应用程序的性能。
当URL重写可能违反缓存逻辑时，请防止响应缓存。
该模块通过更改某些缓存属性或完全禁用缓存来控制输出缓存。如果该模块已被IIS配置或IIS管道中的任何其他模块禁用，则无法启用输出缓存。输出缓存的控制如下：

该模块始终设置用户模式缓存设置VariantByHeader =“ HTTP_X_ORIGINAL_URL”。这样可以确保在启用用户模式缓存时，模块会考虑原始URL来构造用于缓存条目的键。
如果重写规则集使用的服务器变量的值在整个过程的生命周期中都是恒定的，或者是从请求的URL派生的，则对于输出缓存而言，规则集被认为是安全的。这意味着，URL重写模块将不会以设置步骤1中所述的方式设置alterByHeader以外的任何方式更改现有的缓存策略。

在重写规则中使用以下服务器变量时，不会对输出缓存策略产生任何影响：

“ CACHE_URL”
“ DOCUMENT_ROOT”
“ HTTP_URL”
“ HTTP_HOST”
“ PATH_INFO”
“ PATH_TRANSLATED”
“请求参数”
“ REQUEST_FILENAME”
“ REQUEST_URI”
“ SCRIPT_FILENAME”
“ SCRIPT_NAME”
“ SCRIPT_TRANSLATED”
“ UNENCODED_URL”
“ URL”
“ URL_PATH_INFO”
“” APP_POOL_ID“
“ APPL_MD_PATH”
“ APPL_PHYSICAL_PATH”
“ GATEWAY_INTERFACE”
“ SERVER_SOFTWARE”
“ SSI_EXEC_DISABLED”
如果重写规则集使用上面列表中未提及的任何服务器变量，则该规则集被视为对输出缓存不安全。这意味着无论是否重写了请求URL，URL重写模块都会为所有请求禁用内核模式缓存。此外，该模块将通过设置高速缓存属性variableByValue包含规则集中使用的所有服务器变量值的串联字符串，来更改用户模式高速缓存的高速缓存策略。

字符串函数
可以使用三种字符串函数来更改重写规则操作中的值以及任何条件：

ToLower-返回转换为小写的输入字符串。
UrlEncode-返回转换为URL编码格式的输入字符串。如果重写规则中的替换URL包含特殊字符（例如非ASCII或URI不安全字符），则可以使用此功能。
UrlDecode-解码URL编码的输入字符串。此功能可用于在与模式匹配之前对条件输入进行解码。
可以使用以下语法来调用这些函数：

JSON格式

复制
{function_name:any_string}
其中“ function_name”可以位于以下各项中：“ ToLower”，“ UrlEncode”，“ UrlDecode”。“ Any_string”可以是文字字符串，也可以是使用服务器变量或反向引用构建的字符串。例如，以下是字符串函数的有效调用：

JSON格式

复制
{ToLower:DEFAULT.HTM}
{UrlDecode:{REQUEST_URI}}
{UrlEncode:{R:1}.aspx?p=[résumé]}
可以在重写规则中的以下位置使用字符串函数：

条件输入字符串
在规则替换字符串中，特别是：

重写和重定向操作的url属性
CustomResponse操作的statusLine和responseLine属性
使用ToLower函数的规则示例：

XML格式

复制
<rule name="Redirect to canonical url">
<match url="^(.+)" /> <!-- rule back-reference is captured here -->
<conditions>
<!-- Check whether the requested domain is in canonical form -->
<add input="{HTTP_HOST}" type="Pattern" pattern="^www\.mysite\.com$" negate="true" />
</conditions>
<!-- Redirect to canonical url and convert URL path to lowercase -->
<action type="Redirect" url="http://www.mysite.com/{tolower:{R:1}}" RedirectType="Found" />
</rule>
使用UrlEncode函数的规则示例：

XML格式

复制
<rules>
<rule name="UrlEncode example" stopProcessing="true">
<match url="resume" />
<action type="Rewrite" url="default.aspx?name={UrlEncode:résumé}"/>
</rule>
使用UrlDecode函数的规则示例：

XML格式

复制
<rules>
<rule name="UrlDecode example">
<match url="default.aspx" />
<conditions>
<add input="{UrlDecode:{QUERY_STRING}}" pattern="résumé" />
</conditions>
<action type="Rewrite" url="default.aspx?type=resume" />
</rule>
</rules>

改写地图
重写映射是名称-值对的任意集合，可在重写规则内使用它们在重写期间生成替换URL。当您有大量的重写规则并且所有这些规则都使用静态字符串时（即未使用任何模式匹配时），重写映射特别有用。在这些情况下，您可以定义输入URL和替换URL之间的键和值，而不是定义大量简单的重写规则，而将所有映射放入重写映射中。然后，要基于输入URL查找替代URL，您将拥有一个引用重写映射的重写规则。

重写映射定义了名称-值对字符串的命名集合，如以下示例所示：

XML格式

复制
<rewriteMap name="MyRewriteMap" defaultValue="">
<add key="a.html" value="b.html" />
<add key="c.aspx" value="d.aspx" />
<add key="e.php" value="f.php" />
</rewriteMap>
重写映射由其名称唯一标识，并且可以包含零个或多个键值条目。此外，重写映射可以指定找不到密钥时要使用的默认值。这是通过使用defaultValue属性控制的。默认情况下，空字符串用作默认值。

除文件级别外，任何配置级别上都可以有任意数量的重写映射。重写映射位于<rewriteMaps>集合元素内。

使用以下语法在重写规则中引用了重写映射：

JSON格式

复制
{RewriteMapName:Key}
其中Key参数可以是任何任意字符串，并且可以包括对规则或条件模式的反向引用。例如，以下是重写映射的有效用法：

JSON格式

复制
{MyRewriteMap:contoso/{R:1}/test/{C:1}}
{MyRewriteMap:a.html}
{MyRewriteMap:{R:1}?{C:1}&contoso=test}
对重写映射的引用将替换为通过使用作为重写映射引用内的参数传递的键查找的值。如果未找到密钥，则使用该重写映射的默认值。

重写地图可重写规则中的以下位置被引用：

条件输入字符串
在规则替换字符串中，特别是：

重写和重定向操作的url属性
状态行和responseLine的CustomResponse行动
示例1：重写映射定义如下：

XML格式

复制
<rewrite>
<rewriteMaps>
<rewriteMap name="StaticRewrites" defaultValue="">
<add key="/diagnostics" value="/default.aspx?tabid=2&amp;subtabid=29" />
<add key="/webcasts" value="/default.aspx?tabid=2&amp;subtabid=24" />
<add key="/php" value="/default.aspx?tabid=7116" />
</rewriteMap>
</rewriteMaps>
</rewrite>
并且重写规则定义如下：

XML格式

复制
<rewrite>
<rule name="Rewrite Rule">
<match url=".*" />
<conditions>
<add input="{StaticRewrites:{REQUEST_URI}}" pattern="(.+)" />
</conditions>
<action type="Rewrite" url="{C:1}"/>
</rule>
</rewrite>
所请求的URL / 诊断将被重写为/default.aspx?tabid=2&subtabid=29。
所请求的URL / 网络广播将被重写为/default.aspx?tabid=2&subtabid=24。
所请求的URL / php将被重写为/default.aspx?tabid=7116。
所请求的URL / default.aspx将不会被重写，因为重写映射不包含带有key =“ / default.aspx”的元素；因此，重写映射将返回与条件模式不匹配的空字符串，因此将不执行规则操作。

示例2：重写映射定义如下：

XML格式

复制
<rewrite>
<rewriteMaps>
<rewriteMap name="StaticRedirects" defaultValue="">
<add key="/default.aspx?tabid=2&amp;subtabid=29" value="/diagnostics" />
<add key="/default.aspx?tabid=2&amp;subtabid=24" value="/webcasts" />
<add key="/default.aspx?tabid=7116" value="/php" />
</rewriteMap>
</rewriteMaps>
</rewrite>
并且重写规则定义如下：

XML格式

复制
<rewrite>
<rule name="Redirect rule">
<match url=".*" />
<conditions>
<add input="{StaticRedirects:{REQUEST_URI}}" pattern="(.+)" />
</conditions>
<action type="Redirect" url="http://www.contoso.com{C:1}" redirectType="Found" />
</rule>
</rewrite>
请求的URL /default.aspx?tabid=2&subtabid=29将重定向到http://www.contoso.com/diagnostics。
请求的URL /default.aspx?tabid=2&subtabid=24将被重定向到http://www.contoso.com/webcasts。
所请求的URL /default.aspx?tabid=7116将被重定向到http://www.contoso.com/php。
所请求的URL / default.aspx将不会被重定向，因为重写映射不包含带有key =“ / default.aspx”的元素；因此，重写映射将返回与条件模式不匹配的空字符串，因此将不执行规则操作。