URL Rewrite Module Configuration Reference (Referencia de configuración del Módulo URL Rewrite)

de Ruslan Yakushev

En este artículo se proporciona información general sobre el módulo de reescritura de direcciones URL y se explican los conceptos de configuración que usa el módulo.

Introducción a la funcionalidad

El módulo URL Rewrite vuelve a escribir las direcciones URL de solicitud a direcciones sencillas, fáciles de usar y fáciles de usar del motor de búsqueda que se muestran a los usuarios o a las aplicaciones web. La reescritura de direcciones URL usa reglas definidas para evaluar y, a continuación, asignar la dirección URL de solicitud a la dirección definida en la regla antes de procesarla un servidor web de IIS. Puede definir la lógica de reescritura de direcciones URL que incluya expresiones regulares y caracteres comodín, y las reglas se pueden aplicar en función de la dirección URL de solicitud, los encabezados HTTP y las variables de servidor. Aunque el propósito principal del módulo es reescribir las direcciones URL de solicitud a direcciones URL más fáciles, también puede usar el módulo para definir reglas que realizan redireccionamientos, enviar respuestas personalizadas o anular solicitudes.

Introducción a las reglas de reescritura

Una regla de reescritura define la lógica de qué comparar o hacer coincidir la dirección URL de solicitud con y qué hacer si la comparación se realiza correctamente.

Las reglas de reescritura constan de las siguientes partes:

• Patrón : el patrón de regla se usa para especificar la expresión regular o un patrón de caracteres comodín que se usa para buscar coincidencias con cadenas de dirección URL.
• Condiciones : la colección de condiciones opcionales se usa para especificar operaciones lógicas adicionales que se van a realizar si una cadena de dirección URL coincide con el patrón de regla. Dentro de las condiciones, puede comprobar ciertos valores de encabezados HTTP o variables de servidor, o comprobar si la dirección URL solicitada corresponde a un archivo o directorio en un sistema de archivos físico.
• Acción : la acción se usa para especificar qué hacer si la cadena de dirección URL coincide con el patrón de regla y se cumplen todas las condiciones de regla.

Ámbito de reglas de reescritura

Las reglas de reescritura se pueden definir en dos colecciones diferentes:

• <globalRules> : las reglas de esta colección solo se pueden definir en el nivel de servidor. Las reglas globales se usan para definir la lógica de reescritura de direcciones URL de todo el servidor. Estas reglas se definen en el archivo ApplicationHost.config y no se pueden invalidar ni deshabilitar en niveles de configuración inferiores. Las reglas globales siempre funcionan en la ruta de acceso de la dirección URL absoluta (es decir, el URI solicitado sin el nombre del servidor). Estas reglas se evalúan al principio en la canalización de procesamiento de solicitudes de IIS (evento PreBeginRequest ).
• <rules> : las reglas de esta colección se denominan reglas distribuidas y se pueden definir en cualquier nivel de la jerarquía de configuración. Las reglas distribuidas se usan para definir la lógica de reescritura de direcciones URL específica de un ámbito de configuración determinado. Este tipo de regla se puede agregar en cualquier nivel de configuración mediante archivos Web.config o mediante <location> etiquetas dentro de los archivos ApplicationHost.config o Web.config. Las reglas distribuidas funcionan en la ruta de acceso url, en relación con la ubicación del archivo Web.config donde se definen. En los casos en los que las reglas distribuidas se definen dentro de una <location> etiqueta, operan en la ruta de acceso url, en relación con la ruta de acceso especificada para esa <location> etiqueta. Estas reglas se evalúan en el evento BeginRequest en la canalización de IIS.

Evaluación de reglas

Cada nivel de configuración de IIS puede tener cero o más reglas de reescritura definidas. Las reglas se evalúan en el mismo orden en el que se especifican. El módulo de reescritura de direcciones URL procesa el conjunto de reglas mediante el siguiente algoritmo:

1. En primer lugar, la dirección URL coincide con el patrón de una regla. Si no coincide, el módulo de reescritura de direcciones URL detiene inmediatamente el procesamiento de esa regla y pasa a la siguiente regla.
2. Si un patrón coincide y no hay condiciones para la regla, el módulo de reescritura de direcciones URL realiza la acción especificada para esta regla y, a continuación, pasa a la siguiente regla, donde usa la dirección URL sustituida como entrada para esa regla.
3. Si un patrón coincide y hay condiciones para la regla, el módulo de reescritura de direcciones URL evalúa las condiciones. Si la evaluación se realiza correctamente, se realiza la acción de regla especificada y, a continuación, se usa la dirección URL reescrita como entrada para la regla posterior.

Una regla puede tener activada la marca StopProcessing . Cuando se realiza la acción de regla (es decir, la regla coincidente) y esta marca está activada, significa que no se procesarán más reglas posteriores y la solicitud se pasará a la canalización de solicitudes de IIS. De forma predeterminada, esta marca está desactivada.

Herencia de reglas

Si las reglas se definen en varios niveles de configuración, el módulo url Rewrite evalúa las reglas en el orden siguiente:

1. Evalúe todas las reglas globales.
2. Evalúe un conjunto de reglas que incluya reglas distribuidas de los niveles de configuración primarios, así como reglas del nivel de configuración actual. La evaluación se realiza en un orden primario a secundario, lo que significa que las reglas primarias se evalúan primero y las reglas definidas en un último nivel secundario se evalúan en último lugar.

Conservación de la dirección URL original

El módulo URL Rewrite conserva la ruta de acceso de dirección URL solicitada original en las siguientes variables de servidor:

• HTTP_X_ORIGINAL_URL: esta variable de servidor contiene la dirección URL original en formato descodificado;
• UNENCODED_URL: esta variable de servidor contiene la dirección URL original exactamente como lo solicitó un cliente web, con toda la codificación original conservada.

Acceso a elementos de dirección URL desde una regla de reescritura

Es importante comprender cómo se puede acceder a determinadas partes de la cadena de dirección URL desde una regla de reescritura.

Para obtener una dirección URL HTTP con este formato: http(s)://<host>:<port>/<path>?<Querystring>

• La <ruta de acceso> coincide con el patrón de la regla.
• La <cadena> de consulta está disponible en la variable de servidor denominada QUERY_STRING y se puede acceder a ella mediante una condición dentro de una regla.
• El <host> está disponible en la variable de servidor HTTP_HOST y se puede acceder a él mediante una condición dentro de una regla.
• El <puerto> está disponible en la variable de servidor SERVER_PORT y se puede acceder a él mediante una condición dentro de una regla.
• Las variables de servidor SERVER_PORT_SECURE y HTTPS se pueden usar para determinar si se usó una conexión segura. Se puede acceder a estas variables de servidor mediante una condición dentro de una regla.
• La variable de servidor REQUEST_URI se puede usar para acceder a toda la ruta de acceso de dirección URL solicitada, incluida la cadena de consulta.

Por ejemplo, si se realizó una solicitud para esta dirección URL: http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3y se definió una regla de reescritura en el nivel de sitio, a continuación:

• El patrón de regla obtiene la cadena de content/default.aspx dirección URL como entrada.
• La variable de servidor QUERY_STRING contiene tabid=2&subtabid=3.
• La variable de servidor HTTP_HOST contiene www.mysite.com.
• La variable de servidor SERVER_PORT contiene 80.
• La variable de servidor SERVER_PORT_SECURE contiene 0 y HTTPS contiene OFF.
• La variable de servidor REQUEST_URI contiene /content/default.aspx?tabid=2&subtabid=3.
• La variable de servidor PATH_INFO contiene /content/default.aspx.

Tenga en cuenta que la cadena de dirección URL de entrada que se pasa a una regla distribuida siempre es relativa a la ubicación del archivo Web.config donde se define la regla. Por ejemplo, si se realiza una solicitud para http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3y se define una regla de reescritura en el directorio /content , la regla obtiene esta cadena de dirección URL default.aspx como entrada.

Reescritura de la configuración de reglas

Patrón de regla

Se usa un patrón de regla de reescritura para especificar un patrón al que se compara la ruta de acceso de dirección URL actual. Actual, en este contexto, significa el valor de la ruta de acceso url cuando se aplica la regla. Si hubiera alguna regla que precediera a la regla actual, podría haber coincidente con la dirección URL solicitada original y modificarla. La cadena de dirección URL que se evalúa con el patrón no incluye la cadena de consulta. Para incluir la cadena de consulta en la evaluación de reglas, puede usar la variable de servidor QUERY_STRING en la condición de la regla. Para obtener más información, consulte "Usar variables de servidor en reglas de reescritura".

Se especifica un patrón dentro de un <elemento de coincidencia> de una regla de reescritura.

Sintaxis de patrón de regla

La sintaxis del patrón de regla se puede especificar mediante el atributo patternSyntax de una regla. Este atributo se puede establecer en una de las siguientes opciones:

ECMAScript : sintaxis de expresión regular compatible con Perl (compatible con ECMAScript estándar). Esta es una opción predeterminada para cualquier regla. Este es un ejemplo del formato de patrón: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Comodín: sintaxis comodín usada en el módulo de redirección HTTP de IIS. A continuación se muestra un ejemplo de un patrón en este formato: "/Scripts/*_in.???", donde asterisco ("*") significa "coincidir con cualquier número de caracteres y capturarlos en una referencia inversa" y "?" significa que coinciden exactamente con un carácter (no se crea ninguna referencia inversa).

El ámbito del atributo patternSyntax es por regla, lo que significa que se aplica al patrón de la regla actual y a todos los patrones usados dentro de las condiciones de esa regla.

Propiedades del patrón de regla

Un patrón se puede negar mediante el atributo negate del <elemento match> . Cuando se usa este atributo, la acción de regla solo se realiza si la dirección URL actual no coincide con el patrón especificado.

De forma predeterminada, se usa la coincidencia de patrones que no distingue mayúsculas de minúsculas. Para habilitar la distinción entre mayúsculas y minúsculas, puede usar el atributo ignoreCase del <elemento match> de la regla.

Condiciones de reglas

Las condiciones de regla permiten definir lógica adicional para la evaluación de reglas, que se puede basar en entradas distintas de una cadena de dirección URL actual. Cualquier regla puede tener cero o más condiciones. Las condiciones de regla se evalúan después de que la coincidencia del patrón de regla se realice correctamente.

Las condiciones se definen dentro de una <colección de condiciones> de una regla de reescritura. Esta colección tiene un atributo denominado logicalGrouping que controla cómo se evalúan las condiciones. Si una regla tiene condiciones, la acción de regla solo se realiza si el patrón de regla coincide con y:

• Todas las condiciones se evaluaron como true, siempre que se usó logicalGrouping="MatchAll ".
• Al menos una de las condiciones se evaluó como true, siempre que se usó logicalGrouping="MatchAny ".

Una condición se define especificando las siguientes propiedades:

• Cadena de entrada
• Tipo de coincidencia

La entrada de condición especifica qué elemento se va a usar como entrada para la evaluación de la condición. La entrada de condición es una cadena arbitraria que puede incluir variables de servidor y referencias inversas a patrones de condición anteriores o a patrones de regla.

El tipo de coincidencia puede ser una de las tres opciones siguientes:

• IsFile : este tipo de coincidencia se usa para determinar si la cadena de entrada contiene una ruta de acceso física a un archivo en un sistema de archivos. Si no se especifica una cadena de entrada de condición, el módulo URL Rewrite usa la ruta de acceso física del archivo solicitado como valor predeterminado para la entrada de condición. Este tipo de coincidencia solo se puede usar para reglas distribuidas.

• IsDirectory : este tipo de coincidencia se usa para determinar si la cadena de entrada contiene una ruta de acceso física a un directorio de un sistema de archivos. Si no se especifica una cadena de entrada de condición, el módulo URL Rewrite usa la ruta de acceso física del archivo solicitado como valor predeterminado para la entrada de condición. Este tipo de coincidencia solo se puede usar para reglas distribuidas.

• Patrón : este tipo de coincidencia se usa para expresar una condición en la que una cadena de entrada arbitraria coincide con un patrón de expresión regular. Se puede especificar un patrón de condición mediante la sintaxis de expresión regular o mediante la sintaxis de caracteres comodín. El tipo de patrón que se va a usar en una condición depende del valor de la marca patternSyntax definida para la regla a la que pertenece esta condición. Este tipo de condición tiene dos atributos relacionados que controlan la coincidencia de patrones:

  • pattern : use este atributo para especificar el patrón real.
  • ignoreCase : use este atributo para controlar si la coincidencia de patrones para la condición debe distinguir mayúsculas de minúsculas o distinguir mayúsculas de minúsculas.

Además, el resultado de la evaluación de la condición se puede negar mediante el atributo negate . Esto se puede usar para especificar una condición que comprueba si la dirección URL solicitada no es un archivo, como en el ejemplo siguiente:

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

Acción de regla

Se realiza una acción de regla de reescritura cuando la dirección URL actual coincide con el patrón de regla y la evaluación de la condición se realizó correctamente (en función de la configuración de la regla, todas las condiciones coincidentes o cualquiera o varias de las condiciones coincidentes). Hay varios tipos de acciones disponibles y el atributo type del <elemento de configuración de acción> se puede usar para especificar qué acción realiza la regla. En las secciones siguientes se describen diferentes tipos de acción y las opciones de configuración relacionadas con tipos de acción específicos.

Acción de reescritura

Una acción Reescritura reemplaza la cadena de dirección URL actual por una cadena de sustitución. Una cadena de sustitución siempre debe especificar la ruta de acceso url (por ejemplo, contoso/test/default.aspx). Tenga en cuenta que las sustituciones que contienen una ruta de acceso física en un sistema de archivos (por ejemplo, C:\inetpub\wwwroot) no se admiten en IIS.

Una acción Reescritura tiene las siguientes opciones de configuración:

• url : esta es la cadena de sustitución que se usará al volver a escribir la dirección URL actual. La dirección URL de sustitución es un valor de cadena que puede incluir lo siguiente:

  • Referencias inversas a los patrones de condición y regla. (Para obtener más información, consulte la sección sobre cómo usar referencias inversas).
  • Variables de servidor. (Para obtener más información, consulte la sección sobre cómo usar variables de servidor).

• appendQueryString : especifica si la cadena de consulta de la dirección URL actual se conserva durante la sustitución. De forma predeterminada, si no se especifica el valor de la marca appendQueryString , se supone que es TRUE. Esto significa que la cadena de consulta de la dirección URL original se anexa a la dirección URL sustituida.

Acción de redirección

Una acción de redireccionamiento indica al módulo URL Rewrite que envíe una respuesta de redirección al cliente. El código de estado de redirección (3xx) se puede especificar como parámetro para esta acción. El campo Ubicación de la respuesta contiene la cadena de sustitución especificada en la regla.

La dirección URL de sustitución de la regla de redireccionamiento se puede especificar en uno de los siguientes formularios:

• Ruta de acceso de dirección URL relativa: contoso/test/default.aspx
• URI absoluto: https://example.com/contoso/test/default.aspx

El uso de una acción de redireccionamiento implica que no se evalúa ninguna regla posterior para la dirección URL actual después de realizar el redireccionamiento.

Una acción redirigir tiene las siguientes opciones de configuración:

• url : usa una cadena de sustitución como una dirección URL de redireccionamiento. Una dirección URL de sustitución es una cadena que puede incluir lo siguiente:

  • Referencias inversas a los patrones de condición y regla. (Para obtener más información, consulte la sección sobre cómo usar referencias inversas).
  • Variables de servidor. (Para obtener más información, consulte la sección sobre cómo usar variables de servidor).

• appendQueryString : especifica si la cadena de consulta de la dirección URL actual debe conservarse durante la sustitución. De forma predeterminada, si no se especifica la marca AppendQueryString , se supone que es TRUE. Esto significa que la cadena de consulta de la dirección URL original se anexa a la dirección URL sustituida.

• redirectType : especifica el código de estado que se va a usar durante la redirección:

  • 301 – Permanente
  • 302 – Encontrado
  • 303 – Ver otros
  • 307 – Temporal

Acción CustomResponse

Una acción CustomResponse hace que el módulo URL Rewrite responda al cliente HTTP mediante un código de estado, un subcódigo y un motivo especificados por el usuario. El uso de una acción CustomResponse implica que no se evalúa ninguna regla posterior para la dirección URL actual después de realizar esta acción.

La acción CustomResponse tiene las siguientes opciones de configuración:

• statusCode: especifica el código de estado que se va a usar en respuesta al cliente.
• subStatusCode : especifica el código de subestado que se va a usar en respuesta al cliente.
• statusReason : especifica la frase de motivo que se va a usar con el código de estado.
• statusDescription : especifica la descripción de una línea que se va a colocar en el cuerpo de la respuesta.

Acción AbortRequest

Una acción AbortRequest hace que el módulo URL Rewrite quite la conexión HTTP para la solicitud actual. La acción no tiene ningún parámetro. El uso de esta acción implica que no se evalúa ninguna regla posterior para la dirección URL actual después de realizar esta acción.

Ninguna acción

Se usa una acción None para especificar que no se realiza ninguna acción.

Uso de variables de servidor en reglas de reescritura

Las variables de servidor proporcionan información adicional sobre las solicitudes HTTP actuales. Puede usar esta información para tomar decisiones de reescritura o para redactar la dirección URL reescrita. Se puede hacer referencia a las variables de servidor en las siguientes ubicaciones dentro de las reglas de reescritura:

• En la cadena de entrada de condición

• En las cadenas de sustitución de reglas, en concreto:

  • Atributo url de la acción Rewrite y Redirect
  • statusLine y responseLine de una acción CustomResponse

Se puede hacer referencia a las variables de servidor mediante la sintaxis {VARIABLE_NAME}. Por ejemplo, la siguiente condición usa la variable de servidor QUERY_STRING:

<add input="{QUERY_STRING}" pattern="id=([0-9]+)" />

Las variables de servidor también se pueden usar para acceder a encabezados HTTP desde la solicitud actual. Cualquier encabezado HTTP proporcionado por la solicitud actual se representa como una variable de servidor que tiene un nombre generado de acuerdo con esta convención de nomenclatura:

1. Todos los símbolos de guion ("-") del nombre del encabezado HTTP se convierten en símbolos de subrayado ("_").
2. Todas las letras del nombre del encabezado HTTP se convierten en mayúsculas.
3. El prefijo "HTTP_" se agrega al nombre del encabezado.

Por ejemplo, para acceder al encabezado HTTP "user-agent" desde una regla de reescritura, puede usar la variable de servidor {HTTP_USER_AGENT}.

Uso de referencias inversas en reglas de reescritura

Las partes de las reglas o las entradas de condiciones pueden capturarse en referencias inversas. A continuación, se pueden usar para construir direcciones URL de sustitución dentro de acciones de reglas o para construir cadenas de entrada para las condiciones de regla.

Las referencias inversas se generan de maneras diferentes, en función del tipo de sintaxis de patrón que se use para la regla. Cuando se usa una sintaxis de patrón ECMAScript, se puede crear una referencia inversa colocando paréntesis alrededor de la parte del patrón que debe capturar la referencia inversa. Por ejemplo, el patrón ([0-9]+)/([a-z]+).html capturará 07 y el artículo en referencias inversas de esta dirección URL solicitada: 07/article.html. Cuando se usa la sintaxis de patrón "Comodín", las referencias inversas siempre se crean cuando se usa un símbolo asterisco (*) en el patrón. No se crean referencias inversas cuando se usa "?" en el patrón . Por ejemplo, el patrón */*.html capturará contoso y probará las referencias inversas de esta dirección URL solicitada: contoso/test.html.

El uso de referencias inversas es el mismo independientemente de la sintaxis de patrón que se usó para capturarlas. Las referencias inversas se pueden usar en las siguientes ubicaciones dentro de las reglas de reescritura:

• En cadenas de entrada de condición

• En las acciones de regla, en concreto:

  • Atributo url de la acción Rewrite y Redirect
  • statusLine y responseLine de una acción CustomResponse

• En un parámetro de clave para la asignación de reescritura

Las referencias inversas a los patrones de condición se identifican mediante {C:N} donde N es de 0 a 9. Las referencias inversas a los patrones de regla se identifican mediante {R:N} donde N es de 0 a 9. Tenga en cuenta que para ambos tipos de referencias inversas, {R:0} y {C:0}, contendrán la cadena coincidente.

Por ejemplo, en este patrón:

^(www\.)(.*)$

Para la cadena: www.foo.com las referencias inversas se indexarán de la siguiente manera:

{C:0} - www.foo.com
{C:1} - www.
{C:2} - foo.com

Dentro de una acción de regla, puede usar las referencias inversas al patrón de regla y a la última condición coincidente de esa regla. Dentro de una cadena de entrada de condición, puede usar las referencias inversas al patrón de regla y a la condición coincidente anteriormente.

En el ejemplo de regla siguiente se muestra cómo se crean y hacen referencia a las referencias inversas:

<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>

Interacción con el almacenamiento en caché de salida de IIS

El módulo de reescritura de direcciones URL controla el comportamiento de la caché de salida de IIS para:

1. Utilice de forma óptima el modo kernel y el almacenamiento en caché de salida del modo de usuario de las respuestas para las direcciones URL reescritas, lo que mejora el rendimiento de la aplicación web que usa el módulo de reescritura de direcciones URL.
2. Impedir el almacenamiento en caché de respuestas, cuando se puede infringir la lógica de almacenamiento en caché debido a la reescritura de direcciones URL.

El módulo controla el almacenamiento en caché de salida modificando determinadas propiedades de almacenamiento en caché o deshabilitando el almacenamiento en caché por completo. El módulo no puede habilitar el almacenamiento en caché de salida si la configuración de IIS la ha deshabilitado o cualquier otro módulo de la canalización de IIS. El almacenamiento en caché de salida se controla de la siguiente manera:

1. El módulo siempre establece la configuración de caché en modo de usuario varyByHeader="HTTP_X_ORIGINAL_URL". Esto garantiza que cuando el almacenamiento en caché del modo de usuario esté habilitado, el módulo tenga en cuenta la dirección URL original para construir una clave para la entrada de caché.

2. Si un conjunto de reglas de reescritura usa variables de servidor con valores que son constantes durante toda la vida útil del proceso o se derivan de la dirección URL solicitada, el conjunto de reglas se considera seguro para el almacenamiento en caché de salida. Esto significa que el módulo de reescritura de direcciones URL no modificará la directiva de almacenamiento en caché existente de ninguna manera que no sea establecer varyByHeader , como se describe en el paso 1.

   Las siguientes variables de servidor, cuando se usan en reglas de reescritura, no provocan ningún efecto en la directiva de almacenamiento en caché de salida:

   • "CACHE_URL"
   • "DOCUMENT_ROOT"
   • "HTTP_URL"
   • "HTTP_HOST"
   • "PATH_INFO"
   • "PATH_TRANSLATED"
   • "QUERY_STRING"
   • "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"

3. Si un conjunto de reglas de reescritura usa cualquier variable de servidor no mencionada en la lista anterior, el conjunto de reglas se considera no seguro para el almacenamiento en caché de salida. Esto significa que el módulo de reescritura de direcciones URL deshabilitará el almacenamiento en caché del modo kernel para todas las solicitudes si se reescribieron o no las direcciones URL de la solicitud. Además, el módulo modificará la directiva de almacenamiento en caché para la caché en modo de usuario estableciendo la propiedad de almacenamiento en caché varyByValue para contener la cadena concatenada de todos los valores de variables de servidor usados en el conjunto de reglas.

Funciones de cadena

Hay tres funciones de cadena disponibles para cambiar los valores dentro de una acción de regla de reescritura, así como cualquier condición:

• ToLower : devuelve la cadena de entrada convertida en minúsculas.
• UrlEncode : devuelve la cadena de entrada convertida en formato con codificación URL. Esta función se puede usar si la dirección URL de sustitución de la regla de reescritura contiene caracteres especiales (por ejemplo, caracteres no ASCII o URI no seguros).
• UrlDecode : descodifica la cadena de entrada con codificación URL. Esta función se puede usar para descodificar una entrada de condición antes de compararla con un patrón.

Las funciones se pueden invocar mediante la sintaxis siguiente:

{function_name:any_string}

Donde "function_name" puede estar en eof the following: "ToLower", "UrlEncode", "UrlDecode". "Any_string" puede ser una cadena literal o una cadena creada mediante variables de servidor o referencias inversas. Por ejemplo, las siguientes son invocaciones válidas de funciones de cadena:

{ToLower:DEFAULT.HTM}
{UrlDecode:{REQUEST_URI}}
{UrlEncode:{R:1}.aspx?p=[résumé]}

Las funciones de cadena se pueden usar en las siguientes ubicaciones dentro de las reglas de reescritura:

• En cadenas de entrada de condición

• En las cadenas de sustitución de reglas, en concreto:

  • Atributo url de acciones de reescritura y redirección
  • atributos statusLine y responseLine de una acción CustomResponse

Ejemplo de una regla que usa la función ToLower :

<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>

Ejemplo de una regla que usa la función UrlEncode :

<rules>
   <rule name="UrlEncode example" stopProcessing="true">
   <match url="resume" />
   <action type="Rewrite" url="default.aspx?name={UrlEncode:résumé}"/>
</rule>

Ejemplo de una regla que usa la función UrlDecode :

<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>

Mapas de reescritura

Una asignación de reescritura es una colección arbitraria de pares nombre-valor que se pueden usar en reglas de reescritura para generar la dirección URL de sustitución durante la reescritura. Las asignaciones de reescritura son especialmente útiles cuando tiene un gran conjunto de reglas de reescritura y todas estas reglas usan cadenas estáticas (es decir, cuando no se usa ninguna coincidencia de patrones). En esos casos, en lugar de definir un gran conjunto de reglas de reescritura simples, puede colocar todas las asignaciones en la asignación de reescritura como claves y valores entre la dirección URL de entrada y la dirección URL de sustitución. A continuación, para buscar la dirección URL de sustitución en función de la dirección URL de entrada, tendrá una regla de reescritura que haga referencia a la asignación de reescritura.

Una asignación de reescritura define una colección con nombre de cadenas de par nombre-valor, como en el ejemplo siguiente:

<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>

Un mapa de reescritura se identifica de forma única por su nombre y puede contener cero o más entradas de clave-valor. Además, una asignación de reescritura puede especificar el valor predeterminado que se usará cuando no se encuentra una clave. Esto se controla mediante el atributo defaultValue . De forma predeterminada, se usa una cadena vacía como valor predeterminado.

Puede haber cualquier número de asignaciones de reescritura en cualquier nivel de configuración, excepto el nivel de archivo. Los mapas de reescritura se encuentran en el <elemento de colección reescritura Mapas>.

Se hace referencia a las asignaciones de reescritura dentro de una regla de reescritura mediante la sintaxis siguiente:

{RewriteMapName:Key}

Donde el parámetro Key puede ser cualquier cadena arbitraria y puede incluir referencias inversas a patrones de regla o condición. Por ejemplo, los siguientes son usos válidos de una asignación de reescritura:

{MyRewriteMap:contoso/{R:1}/test/{C:1}}
{MyRewriteMap:a.html}
{MyRewriteMap:{R:1}?{C:1}&contoso=test}

Una referencia a una asignación de reescritura se sustituye por el valor que se ha buscado mediante el uso de la clave pasada como parámetro dentro de una referencia de mapa de reescritura. Si no se encontró una clave, se usa el valor predeterminado de esa asignación de reescritura.

Se puede hacer referencia a un mapa de reescritura en las siguientes ubicaciones dentro de las reglas de reescritura:

• En la cadena de entrada de condición

• En las cadenas de sustitución de reglas, en concreto:

  • Atributo url de acciones de reescritura y redirección
  • statusLine y responseLine de acciones CustomResponse

Ejemplo 1: Con una asignación de reescritura definida como se indica a continuación:

<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>

Y una regla de reescritura definida de la siguiente manera:

<rewrite>
 <rule name="Rewrite Rule">
  <match url=".*" />
  <conditions>
   <add input="{StaticRewrites:{REQUEST_URI}}" pattern="(.+)" />
  </conditions>
  <action type="Rewrite" url="{C:1}"/>
 </rule>
</rewrite>

La dirección URL /diagnostic solicitada se reescribirá como /default.aspx?tabid=2&subtabid=29.
La dirección URL solicitada /webcasts se reescribirá en /default.aspx?tabid=2&subtabid=24.
La dirección URL solicitada /php se volverá a escribir en /default.aspx?tabid=7116.
La dirección URL solicitada /default.aspx no se volverá a escribir porque la asignación de reescritura no contiene un elemento con key="/default.aspx"; por lo tanto, la asignación de reescritura devolverá una cadena vacía que no coincidirá con el patrón de condición, por lo que no se realizará la acción de regla.

Ejemplo 2: Con una asignación de reescritura definida como se indica a continuación:

<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>

Y una regla de reescritura definida de la siguiente manera:

<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>

La dirección URL solicitada /default.aspx?tabid=2&subtabid=29 se redirigirá a http://www.contoso.com/diagnostics.
La dirección URL solicitada /default.aspx?tabid=2&subtabid=24 se redirigirá a http://www.contoso.com/webcasts.
La dirección URL solicitada /default.aspx?tabid=7116 se redirigirá a http://www.contoso.com/php.
La dirección URL solicitada /default.aspx no se redirigirá porque la asignación de reescritura no contiene un elemento con key="/default.aspx"; por lo tanto, el mapa de reescritura devolverá una cadena vacía que no coincidirá con el patrón de condición, por lo que no se realizará la acción de regla.