Referência de configuração do Módulo de Reconfiguração de URL

  • Artigo

por Ruslan Yakushev

Este artigo fornece uma visão geral do módulo de regravação de URL e explica os conceitos de configuração usados pelo módulo.

Visão geral da funcionalidade

O Módulo de Regravação de URL regrava URLs de solicitação em endereços simples, fáceis de usar e amigáveis para mecanismos de pesquisa que são exibidos aos usuários ou em aplicativos Web. A Reconfiguração de URL usa regras definidas para avaliar e mapear a URL de solicitação para o endereço definido na regra antes de ser processada por um servidor Web IIS. Você pode definir a lógica de reconfiguração de URL que inclui expressões regulares e curingas, e as regras podem ser aplicadas com base na URL de solicitação, cabeçalhos HTTP e variáveis de servidor. Embora o objetivo principal do módulo seja reescrever URLs de solicitação para URLs mais amigáveis, você também pode usar o módulo para definir regras que executam redirecionamentos, enviam respostas personalizadas ou anulam solicitações.

Visão geral de reescrever regras

Uma regra de regravação define a lógica com a qual comparar ou corresponder a URL da solicitação e o que fazer se a comparação for bem-sucedida.

As regras de reescrita consistem nas seguintes partes:

  • Padrão – O padrão de regra é usado para especificar a expressão regular ou um padrão curinga usado para corresponder a cadeias de caracteres de URL.
  • Condições – A coleção de condições opcionais é usada para especificar operações lógicas adicionais a serem executadas se uma cadeia de caracteres de URL corresponder ao padrão de regra. Dentro das condições, você pode verificar determinados valores de cabeçalhos HTTP ou variáveis de servidor ou verificar se a URL solicitada corresponde a um arquivo ou diretório em um sistema de arquivos físico.
  • Ação – A ação é usada para especificar o que fazer se a cadeia de caracteres da URL corresponder ao padrão da regra e todas as condições da regra forem atendidas.

Escopo de reescrever regras

As regras de regravação podem ser definidas em duas coleções diferentes:

  • <globalRules> – As regras nesta coleção podem ser definidas apenas no nível do servidor. As regras globais são usadas para definir a lógica de reconfiguração de URL em todo o servidor. Essas regras são definidas no arquivo ApplicationHost.config e não podem ser substituídas ou desabilitadas em nenhum nível de configuração inferior. As regras globais sempre operam no caminho absoluto da URL (ou seja, o URI solicitado sem o nome do servidor). Essas regras são avaliadas no início do pipeline de processamento de solicitações do IIS (evento PreBeginRequest ).
  • <rules> – As regras nesta coleção são chamadas de regras distribuídas e podem ser definidas em qualquer nível na hierarquia de configuração. As regras distribuídas são usadas para definir a lógica de reescrita de URL específica para um escopo de configuração específico. Esse tipo de regra pode ser adicionado em qualquer nível de configuração usando arquivos Web.config ou marcas nos <location> arquivos ApplicationHost.config ou Web.config. As regras distribuídas operam no caminho da URL, em relação ao local do arquivo Web.config onde são definidas. Nos casos em que as regras distribuídas são definidas dentro de uma <location> tag, elas operam no caminho da URL, em relação ao caminho especificado para essa <location> tag. Essas regras são avaliadas no evento BeginRequest no pipeline do IIS.

Avaliação de regras

Cada nível de configuração no IIS pode ter zero ou mais regras de regravação definidas. As regras são avaliadas na mesma ordem em que são especificadas. O módulo de regravação de URL processa o conjunto de regras usando o seguinte algoritmo:

  1. Primeiro, a URL é comparada com o padrão de uma regra. Se não corresponder, o Módulo de Regravação de URL interromperá imediatamente o processamento dessa regra e passará para a próxima regra.
  2. Se um padrão corresponder e não houver condições para a regra, o Módulo de Regravação de URL executará a ação especificada para essa regra e, em seguida, passará para a próxima regra, onde usará a URL substituída como uma entrada para essa regra.
  3. Se um padrão corresponder e houver condições para a regra, o Módulo de Regravação de URL avaliará as condições. Se a avaliação for bem-sucedida, a ação de regra especificada será executada e, em seguida, a URL reescrita será usada como entrada para a regra subsequente

Uma regra pode ter o sinalizador StopProcessing ativado. Quando a ação de regra é executada (ou seja, a regra corresponde) e esse sinalizador está ativado, isso significa que nenhuma outra regra subsequente será processada e a solicitação será passada para o pipeline de solicitação do IIS. Por padrão, esse sinalizador está desativado.

Herança de regras

Se as regras forem definidas em vários níveis de configuração, o Módulo de Regravação de URL avaliará as regras na seguinte ordem:

  1. Avalie todas as regras globais.
  2. Avalie um conjunto de regras que inclua regras distribuídas dos níveis de configuração pai, bem como regras do nível de configuração atual. A avaliação é realizada em uma ordem de pai para filho, o que significa que as regras dos pais são avaliadas primeiro e as regras definidas em um último nível filho são avaliadas por último.

Preservando a URL original

O módulo de regravação de URL preserva o caminho de URL solicitado original nas seguintes variáveis de servidor:

  • HTTP_X_ORIGINAL_URL – esta variável de servidor contém a URL original em formato decodificado;
  • UNENCODED_URL – essa variável de servidor contém a URL original exatamente como foi solicitada por um cliente Web, com toda a codificação original preservada.

Acessando partes de URL a partir de uma regra de regravação

É importante entender como certas partes da cadeia de caracteres de URL podem ser acessadas a partir de uma regra de regravação.

Para uma URL HTTP neste formato: http(s)://<host>:<port>/<path>?<querystring>

  • O <caminho> é combinado com o padrão da regra.
  • A <cadeia de caracteres de consulta> está disponível na variável de servidor chamada QUERY_STRING e pode ser acessada usando uma condição dentro de uma regra.
  • O <host> está disponível na variável de servidor HTTP_HOST e pode ser acessado usando uma condição dentro de uma regra.
  • A <porta> está disponível na variável de servidor SERVER_PORT e pode ser acessada usando uma condição dentro de uma regra.
  • As variáveis de servidor SERVER_PORT_SECURE e HTTPS podem ser usadas para determinar se uma conexão segura foi usada. Essas variáveis de servidor podem ser acessadas usando uma condição dentro de uma regra.
  • A variável de servidor REQUEST_URI pode ser usada para acessar todo o caminho de URL solicitado, incluindo a cadeia de caracteres de consulta.

Por exemplo, se uma solicitação foi feita para esta URL: http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3e uma regra de regravação foi definida no nível do site, então:

  • O padrão de regra obtém a cadeia de caracteres de content/default.aspx URL como uma entrada.
  • A variável de servidor QUERY_STRING contém tabid=2&subtabid=3.
  • A variável de servidor HTTP_HOST contém www.mysite.com.
  • A variável de servidor SERVER_PORT contém 80.
  • A variável de servidor SERVER_PORT_SECURE contém 0 e HTTPS contém OFF.
  • A variável de servidor REQUEST_URI contém /content/default.aspx?tabid=2&subtabid=3.
  • A variável de servidor PATH_INFO contém /content/default.aspx.

Observe que a cadeia de caracteres da URL de entrada passada para uma regra distribuída é sempre relativa ao local do arquivo Web.config onde a regra é definida. Por exemplo, se uma solicitação for feita para http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3o , e uma regra de regravação for definida no diretório /content , a regra obterá essa cadeia de caracteres de URL default.aspx como uma entrada.

Reescrever configuração de regra

Padrão de regra

Um padrão de regra de regravação é usado para especificar um padrão ao qual o caminho de URL atual é comparado. Current, nesse contexto, significa o valor do caminho da URL quando a regra é aplicada. Se houvesse alguma regra que precedesse a regra atual, ela poderia ter correspondido à URL solicitada original e a modificado. A cadeia de caracteres de URL avaliada em relação ao padrão não inclui a cadeia de caracteres de consulta. Para incluir a cadeia de caracteres de consulta na avaliação da regra, você pode usar a variável de servidor QUERY_STRING na condição da regra. Para obter mais informações, consulte "Usando variáveis de servidor em regras de regravação".

Um padrão é especificado dentro de um <elemento de correspondência> de uma regra de regravação.

Sintaxe do padrão de regra

A sintaxe do padrão de regra pode ser especificada usando o atributo patternSyntax de uma regra. Esse atributo pode ser definido como uma das seguintes opções:

ECMAScript – sintaxe de expressão regular compatível com Perl (compatível com o padrão ECMAScript). Esta é uma opção padrão para qualquer regra. Este é um exemplo do formato de padrão: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Curinga – sintaxe curinga usada no módulo de redirecionamento HTTP do IIS. A seguir está um exemplo de um padrão neste formato: "/Scripts/*_in.???", onde asterisco ("*") significa "corresponder a qualquer número de caracteres e capturá-los em uma referência de retorno" e "?" significa corresponder exatamente a um caractere (nenhuma referência de volta é criada).

O escopo do atributo patternSyntax é por regra, o que significa que ele se aplica ao padrão da regra atual e a todos os padrões usados dentro das condições dessa regra.

Propriedades do padrão de regra

Um padrão pode ser negado usando o <atributo negate do elemento match>. Quando esse atributo é usado, a ação de regra é executada somente se a URL atual não corresponder ao padrão especificado.

Por padrão, a correspondência de padrão que não diferencia maiúsculas de minúsculas é usada. Para habilitar a diferenciação de maiúsculas e minúsculas, você pode usar o atributo ignoreCase do <elemento match> da regra.

Condições da regra

As condições de regra permitem definir lógica adicional para avaliação de regras, que pode ser baseada em entradas diferentes de apenas uma cadeia de caracteres de URL atual. Qualquer regra pode ter zero ou mais condições. As condições da regra são avaliadas depois que a correspondência do padrão de regra é bem-sucedida.

As condições são definidas dentro de uma <coleção de condições> de uma regra de regravação. Essa coleção tem um atributo chamado logicalGrouping que controla como as condições são avaliadas. Se uma regra tiver condições, a ação da regra será executada somente se o padrão da regra corresponder e:

  • Todas as condições foram avaliadas como verdadeiras, desde que fosse utilizado logicalGrouping="MatchAll".
  • Pelo menos uma das condições foi avaliada como verdadeira, desde que logicalGrouping="MatchAny" fosse utilizado.

Uma condição é definida especificando as seguintes propriedades:

  • Cadeia de caracteres de entrada
  • Tipo de correspondência

A entrada de condição especifica qual item usar como entrada para a avaliação da condição. A entrada de condição é uma cadeia de caracteres arbitrária que pode incluir variáveis de servidor e referências retroativas a padrões de condição anteriores e/ou a padrões de regras.

O tipo de correspondência pode ser uma das três opções a seguir:

  • IsFile – Esse tipo de correspondência é usado para determinar se a cadeia de caracteres de entrada contém um caminho físico para um arquivo em um sistema de arquivos. Se uma cadeia de caracteres de entrada de condição não for especificada, o Módulo de Regravação de URL usará o caminho físico do arquivo solicitado como um valor padrão para a entrada de condição. Esse tipo de correspondência pode ser usado somente para regras distribuídas.

  • IsDirectory – Esse tipo de correspondência é usado para determinar se a cadeia de caracteres de entrada contém um caminho físico para um diretório em um sistema de arquivos. Se uma cadeia de caracteres de entrada de condição não for especificada, o Módulo de Regravação de URL usará o caminho físico do arquivo solicitado como um valor padrão para a entrada de condição. Esse tipo de correspondência pode ser usado somente para regras distribuídas.

  • Padrão – Esse tipo de correspondência é usado para expressar uma condição em que uma cadeia de caracteres de entrada arbitrária é comparada a um padrão de expressão regular. Um padrão de condição pode ser especificado usando sintaxe de expressão regular ou usando sintaxe curinga. O tipo de padrão a ser usado em uma condição depende do valor do sinalizador patternSyntax definido para a regra à qual essa condição pertence. Esse tipo de condição tem dois atributos relacionados que controlam a correspondência de padrões:

    • pattern – Use esse atributo para especificar o padrão real.
    • ignoreCase – Use esse atributo para controlar se a correspondência de padrão para a condição deve diferenciar maiúsculas de minúsculas ou não diferenciar maiúsculas de minúsculas.

Além disso, o resultado da avaliação da condição pode ser negado usando o atributo negate . Isso pode ser usado para especificar uma condição que verifica se a URL solicitada NÃO é um arquivo, como no exemplo a seguir:

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

Ação de regra

Uma ação de regra de regravação é executada quando a URL atual corresponde ao padrão de regra e a avaliação da condição é bem-sucedida (dependendo da configuração da regra, todas as condições correspondem ou qualquer uma ou mais das condições correspondidas). Há vários tipos de ações disponíveis, e o atributo type do elemento de configuração de <ação> pode ser usado para especificar qual ação a regra executa. As seções a seguir descrevem diferentes tipos de ação e as opções de configuração relacionadas a tipos de ação específicos.

Ação de regravação

Uma ação Regravar substitui a cadeia de caracteres de URL atual por uma cadeia de caracteres de substituição. Uma cadeia de caracteres de substituição deve sempre especificar o caminho da URL (por exemplo, contoso/test/default.aspx). Observe que as substituições que contêm um caminho físico em um sistema de arquivos (por exemplo, C:\inetpub\wwwroot) não são suportadas no IIS.

Uma ação Regravar tem as seguintes opções de configuração:

  • url – Esta é a cadeia de caracteres de substituição a ser usada ao reescrever a URL atual. A URL de substituição é um valor de cadeia de caracteres que pode incluir o seguinte:

    • Referências retroativas aos padrões de condição e regra. (Para obter mais informações, consulte a seção sobre como usar referências retroativas.)
    • Variáveis de servidor. (Para obter mais informações, consulte a seção sobre como usar variáveis de servidor.)

  • appendQueryString – Especifica se a cadeia de caracteres de consulta da URL atual é preservada durante a substituição. Por padrão, se o valor do sinalizador appendQueryString não for especificado, ele será assumido como TRUE. Isso significa que a cadeia de caracteres de consulta da URL original é anexada à URL substituída.

Ação de redirecionamento

Uma ação de redirecionamento instrui o módulo de regravação de URL a enviar uma resposta de redirecionamento de volta ao cliente. O código de status de redirecionamento (3xx) pode ser especificado como um parâmetro para essa ação. O campo Local da resposta contém a cadeia de caracteres de substituição especificada na regra.

A URL de substituição para a regra de redirecionamento pode ser especificada em uma das seguintes formas:

  • Caminho relativo da URL – contoso/test/default.aspx
  • URI absoluto – https://example.com/contoso/test/default.aspx

O uso de uma ação de redirecionamento implica que nenhuma regra subsequente avaliada para a URL atual após o redirecionamento é executada.

Uma ação de redirecionamento tem as seguintes opções de configuração:

  • url – Usa uma cadeia de caracteres de substituição como uma URL de redirecionamento. Uma URL de substituição é uma cadeia de caracteres que pode incluir o seguinte:

    • Referências retroativas aos padrões de condição e regra. (Para obter mais informações, consulte a seção sobre como usar referências retroativas.)
    • Variáveis de servidor. (Para obter mais informações, consulte a seção sobre como usar variáveis de servidor.)

  • appendQueryString – Especifica se a cadeia de caracteres de consulta da URL atual deve ser preservada durante a substituição. Por padrão, se o sinalizador AppendQueryString não for especificado, ele será assumido como TRUE. Isso significa que a cadeia de caracteres de consulta da URL original é anexada à URL substituída.

  • redirectType – Especifica o código de status a ser usado durante o redirecionamento:

    • 301 – Permanente
    • 302 – Encontrado
    • 303 – Ver outros
    • 307 – Temporário

Ação CustomResponse

Uma ação CustomResponse faz com que o Módulo de Regravação de URL responda ao cliente HTTP usando um código de status, subcódigo e motivo especificados pelo usuário. O uso de uma ação CustomResponse implica que nenhuma regra subsequente é avaliada para a URL atual depois que essa ação é executada.

A ação CustomResponse tem as seguintes opções de configuração:

  • statusCode– Especifica o código de status a ser usado em resposta ao cliente.
  • subStatusCode – Especifica o código de substatus a ser usado em resposta ao cliente.
  • statusReason – Especifica a frase de motivo a ser usada com o código de status.
  • statusDescription – Especifica a descrição de uma linha a ser colocada no corpo da resposta.

Ação AbortRequest

Uma ação AbortRequest faz com que o Módulo de Regravação de URL descarte a conexão HTTP para a solicitação atual. A ação não tem parâmetros. O uso dessa ação implica que nenhuma regra subsequente seja avaliada para a URL atual depois que essa ação for executada.

Nenhuma ação

Uma ação Nenhum é usada para especificar que nenhuma ação é executada.

Usando variáveis de servidor em regras de regravação

As variáveis de servidor fornecem informações adicionais sobre solicitações HTTP atuais. Você pode usar essas informações para tomar decisões de regravação ou para compor a URL reescrita. As variáveis de servidor podem ser referenciadas nos seguintes locais dentro das regras de regravação:

  • Na cadeia de caracteres de entrada de condição

  • Em cadeias de caracteres de substituição de regras, especificamente:

    • atributo url da ação Reescrever e Redirecionar
    • statusLine e responseLine de uma ação CustomResponse

As variáveis de servidor podem ser referenciadas usando a sintaxe {VARIABLE_NAME}. Por exemplo, a seguinte condição usa a variável de servidor QUERY_STRING:

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

As variáveis de servidor também podem ser usadas para acessar cabeçalhos HTTP da solicitação atual. Qualquer cabeçalho HTTP fornecido pela solicitação atual é representado como uma variável de servidor que tem um nome gerado de acordo com esta convenção de nomenclatura:

  1. Todos os símbolos de traço ("-") no nome do cabeçalho HTTP são convertidos em símbolos de sublinhado ("_").
  2. Todas as letras no nome do cabeçalho HTTP são convertidas em maiúsculas.
  3. O prefixo "HTTP_" é adicionado ao nome do cabeçalho.

Por exemplo, para acessar o cabeçalho HTTP "user-agent" de uma regra de regravação, você pode usar a variável de servidor {HTTP_USER_AGENT}.

Usando referências de volta em regras de regravação

Partes de entradas de regras ou condições podem ser capturadas em referências retroativas. Eles podem ser usados para construir URLs de substituição dentro de ações de regras ou para construir cadeias de caracteres de entrada para condições de regra.

As referências de retorno são geradas de maneiras diferentes, dependendo do tipo de sintaxe de padrão usado para a regra. Quando uma sintaxe de padrão ECMAScript é usada, uma referência de retorno pode ser criada colocando parênteses ao redor da parte do padrão que deve capturar a referência de volta. Por exemplo, o padrão ([0-9]+)/([a-z]+).html capturará 07 e artigo em referências retroativas desta URL solicitada: 07/article.html. Quando a sintaxe de padrão "Curinga" é usada, as referências de volta são sempre criadas quando um símbolo de asterisco (*) é usado no padrão. Nenhuma referência de volta é criada quando "?" é usado no padrão. Por exemplo, o padrão */*.html capturará contoso e testará em referências retroativas desta URL solicitada: contoso/test.html.

O uso de referências de volta é o mesmo, independentemente de qual sintaxe de padrão foi usada para capturá-las. As referências retroativas podem ser usadas nos seguintes locais dentro das regras de regravação:

  • Em sequências de entrada de condição

  • Em ações de regras, especificamente:

    • atributo url da ação Reescrever e Redirecionar
    • statusLine e responseLine de uma ação CustomResponse

  • Em um parâmetro-chave para o mapa de regravação

As referências de volta aos padrões de condição são identificadas por {C:N} onde N é de 0 a 9. Referências anteriores a padrões de regras são identificadas por {R:N} onde N é de 0 a 9. Observe que para ambos os tipos de referências anteriores, {R:0} e {C:0}, conterão a cadeia de caracteres correspondente.

Por exemplo, neste padrão:

^(www\.)(.*)$

Para a cadeia de caracteres: www.foo.com as referências traseiras serão indexadas da seguinte forma:

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

Dentro de uma ação de regra, você pode usar as referências de volta ao padrão de regra e à última condição correspondente dessa regra. Dentro de uma cadeia de caracteres de entrada de condição, você pode usar as referências de volta ao padrão de regra e à condição correspondente anteriormente.

O exemplo de regra a seguir demonstra como as referências anteriores são criadas e referenciadas:

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

Interação com o cache de saída do IIS

O módulo de regravação de URL controla o comportamento do cache de saída do IIS para:

  1. Utilize de forma otimizada o cache de saída do modo kernel e do modo de usuário das respostas para URLs reescritas, melhorando assim o desempenho do aplicativo Web que usa o Módulo de Regravação de URL.
  2. Impedir o cache de respostas, quando a lógica de cache pode ser violada devido à regravação de URL.

O módulo controla o cache de saída alterando determinadas propriedades de cache ou desabilitando o cache completamente. O módulo não poderá habilitar o cache de saída se tiver sido desabilitado pela configuração do IIS ou por qualquer outro módulo no pipeline do IIS. O cache de saída é controlado da seguinte maneira:

  1. O módulo sempre define a configuração de cache do modo de usuário varyByHeader="HTTP_X_ORIGINAL_URL". Isso garante que, quando o cache do modo de usuário estiver habilitado, o módulo levará em conta a URL original para construir uma chave para a entrada de cache.

  2. Se um conjunto de regras de regravação usar variáveis de servidor com valores que são constantes durante toda a vida útil do processo ou derivados da URL solicitada, o conjunto de regras é considerado seguro para cache de saída. Isso significa que o Módulo de Regravação de URL não alterará a política de cache existente de outra forma que não seja a configuração varyByHeader , conforme descrito na etapa 1.

    As seguintes variáveis de servidor, quando usadas em regras de regravação, não causam nenhum efeito na diretiva de cache de saída:

    • "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. Se um conjunto de regras de regravação usar qualquer variável de servidor não mencionada na lista acima, o conjunto de regras será considerado inseguro para cache de saída. Isso significa que o Módulo de Regravação de URL desabilitará o cache do modo kernel para todas as solicitações, independentemente de as URLs de solicitação terem sido reescritas ou não. Além disso, o módulo alterará a política de cache para cache de modo de usuário definindo a propriedade de cache varyByValue para conter a cadeia de caracteres concatenada de todos os valores de variáveis de servidor usados no conjunto de regras.

Funções de cadeia de caracteres

Há três funções de cadeia de caracteres disponíveis para alterar os valores em uma ação de regra de regravação, bem como quaisquer condições:

  • ToLower - retorna a cadeia de caracteres de entrada convertida em minúsculas.
  • UrlEncode - retorna a cadeia de entrada convertida para o formato codificado por URL. Essa função pode ser usada se a URL de substituição na regra de regravação contiver caracteres especiais (por exemplo, caracteres não ASCII ou URI-não seguros).
  • UrlDecode - decodifica a cadeia de entrada codificada por URL. Essa função pode ser usada para decodificar uma entrada de condição antes de combiná-la com um padrão.

As funções podem ser invocadas usando a seguinte sintaxe:

{function_name:any_string}

Onde "function_name" pode estar no seguinte: "ToLower", "UrlEncode", "UrlDecode". "Any_string" pode ser uma cadeia de caracteres literal ou uma cadeia de caracteres criada usando variáveis de servidor ou referências retroativas. Por exemplo, a seguir estão invocações válidas de funções de cadeia de caracteres:

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

As funções de cadeia de caracteres podem ser usadas nos seguintes locais dentro das regras de regravação:

  • Em sequências de entrada de condição

  • Em cadeias de caracteres de substituição de regras, especificamente:

    • atributo url das ações Reescrevere Redirecionar
    • statusLine e responseLine atributos de uma ação CustomResponse

Um exemplo de uma regra que usa a função 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>

Um exemplo de uma regra que usa a função UrlEncode :

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

Um exemplo de uma regra que usa a função 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 reescrita

Um mapa de regravação é uma coleção arbitrária de pares nome-valor que pode ser usada dentro de regras de regravação para gerar a URL de substituição durante a regravação. Os mapas de reescrita são particularmente úteis quando você tem um grande conjunto de regras de reescrita, todas elas usando cadeias de caracteres estáticas (ou seja, quando padrões correspondentes não são usados). Nesses casos, em vez de definir um grande conjunto de regras de regravação simples, você pode colocar todos os mapeamentos no mapa de regravação como chaves e valores entre a URL de entrada e a URL de substituição. Em seguida, para procurar a URL de substituição com base na URL de entrada, você terá uma regra de regravação que faz referência ao mapa de regravação.

Um mapa de regravação define uma coleção nomeada de cadeias de caracteres de par nome-valor, como no exemplo a seguir:

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

Um mapa de regravação é identificado exclusivamente por seu nome e pode conter zero ou mais entradas de valor-chave. Além disso, um mapa de regravação pode especificar o valor padrão a ser usado quando uma chave não for encontrada. Isso é controlado usando o atributo defaultValue . Por padrão, uma cadeia de caracteres vazia é usada como um valor padrão.

Pode haver qualquer número de mapas de regravação em qualquer nível de configuração, exceto o nível de arquivo. Os mapas de regravação estão localizados no <elemento de coleção rewriteMaps> .

Os mapas de regravação são referenciados dentro de uma regra de regravação usando a seguinte sintaxe:

{RewriteMapName:Key}

Onde o parâmetro Key pode ser qualquer cadeia de caracteres arbitrária e pode incluir referências de volta a padrões de regra ou condição. Por exemplo, os seguintes são usos válidos de um mapa de regravação:

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

Uma referência a um mapa de regravação é substituída pelo valor que foi pesquisado usando a chave passada como parâmetro dentro de uma referência de mapa de regravação. Se uma chave não foi encontrada, o valor padrão para esse mapa de regravação será usado.

Um mapa de regravação pode ser referenciado nos seguintes locais dentro das regras de regravação:

  • Na sequência de entrada de condição

  • Em cadeias de caracteres de substituição de regras, especificamente:

    • atributo url das ações Reescrevere Redirecionar
    • statusLine e responseLine das ações CustomResponse

Exemplo 1: Com um mapa de regravação definido da seguinte maneira:

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

E uma regra de reescrita definida da seguinte forma:

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

A URL /diagnostic solicitada será reescrita como /default.aspx?tabid=2&subtabid=29.
A URL /webcasts solicitada será reescrita para /default.aspx?tabid=2&subtabid=24.
A URL /php solicitada será reescrita para /default.aspx?tabid=7116.
A URL /default.aspx solicitada não será reescrita porque o mapa de regravação não contém um elemento com key="/default.aspx"; portanto, o mapa de regravação retornará uma cadeia de caracteres vazia que não corresponderá ao padrão de condição, portanto, a ação de regra não será executada.

Exemplo 2: Com um mapa de regravação definido da seguinte maneira:

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

E uma regra de reescrita definida da seguinte forma:

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

A URL solicitada /default.aspx?tabid=2&subtabid=29 será redirecionada para http://www.contoso.com/diagnostics.
A URL solicitada /default.aspx?tabid=2&subtabid=24 será redirecionada para http://www.contoso.com/webcasts.
A URL solicitada /default.aspx?tabid=7116 será redirecionada para http://www.contoso.com/php.
A URL /default.aspx solicitada não será redirecionada porque o mapa de regravação não contém um elemento com key="/default.aspx"; portanto, o mapa de regravação retornará uma cadeia de caracteres vazia que não corresponderá ao padrão de condição, portanto, a ação de regra não será executada.