Compartilhar via

Referência de configuração do módulo de regravação de URL

por Ruslan Yakushev

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

Visão geral da funcionalidade

O Módulo de Reescrita de URL transforma as URLs de solicitações em endereços simples, amigáveis ao usuário e otimizados para mecanismos de busca, que são exibidos para usuários ou em aplicativos Web. O Rewrite de URL utiliza regras definidas para avaliar e mapear a URL solicitada ao endereço definido na regra antes de ser processada por um servidor Web IIS. Você pode definir a lógica de reescrita de URL que inclui expressões regulares e curingas, e as regras podem ser aplicadas com base na URL da solicitação, cabeçalhos HTTP e variáveis de servidor. Embora a principal finalidade 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 solicitações de anulação.

Visão geral das regras de regravação

Uma regra de reescrita define a lógica sobre o que comparar ou fazer corresponder à URL da solicitação, e o que fazer se a comparação for bem sucedida.

As regras de regravação 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 às 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 de URL corresponder ao padrão de regra e todas as condições de regra forem atendidas.

Regras de reescrita

As regras de reescrita podem ser definidas em duas coleções diferentes:

  • <globalRules> – As regras nesta coleção só podem ser definidas no nível do servidor. As regras globais são usadas para definir a lógica de reescrita 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 níveis de configuração inferiores. As regras globais sempre operam no caminho da URL absoluta (ou seja, o URI solicitado sem o nome do servidor). Essas regras são avaliadas no início do pipeline de processamento de solicitação 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 usando <location> marcas em arquivos ApplicationHost.config ou Web.config. As regras distribuídas operam no caminho da URL em relação ao local do arquivo Web.config em que são definidas. Nos casos em que as regras distribuídas são definidas dentro de uma <location> marca, elas operam no caminho da URL, em relação ao caminho especificado para essa <location> marca. 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 reescrita definidas. As regras são avaliadas na mesma ordem em que são especificadas. O Módulo de Reescrita de URL processa o conjunto de regras usando o seguinte algoritmo:

  1. Primeiro, a URL é comparada ao padrão de uma regra. Se ele não corresponder, o Módulo de Reescrita de URL interromperá imediatamente o processamento dessa regra e irá para a próxima regra.
  2. Se um padrão corresponder e não houver condições para a regra, o Módulo de Reescrita de URL executará a ação especificada para essa regra e, em seguida, irá para a próxima regra, em que ela 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 Reescrita 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 da regra é executada (ou seja, quando a regra é correspondida) e esse indicador é ativado, isso significa que nenhuma outra regra subsequente será processada e a requisição será passada para o pipeline de requisiçã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 Reescrita de URL avaliará as regras na seguinte ordem:

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

Preservando a URL Original

O Módulo de Reescrita de URL preserva o caminho de URL solicitado original nas seguintes variáveis de servidor:

  • HTTP_X_ORIGINAL_URL – essa variável de servidor contém a URL original no 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 de uma regra de reescrita

É importante entender como determinadas partes da cadeia de caracteres de URL podem ser acessadas a partir de uma regra de reescrita.

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

  • O <caminho> é comparado com o padrão da regra.
  • A <querystring> 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.
  • 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 reescrita foi definida no nível do site, em seguida:

  • O padrão de regra recebe a string de URL content/default.aspx como 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 de URL de entrada passada para uma regra distribuída é sempre relativa ao local do arquivo Web.config em que a regra é definida. Por exemplo, se uma solicitação for feita para http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3, e uma regra de reescrita for definida no diretório /content, então a regra receberá essa cadeia de caracteres de URL default.aspx como entrada.

Configuração de Regra de Reescrita

Padrão de regra

Um padrão de regra de reescrita é usado para especificar um padrão ao qual o caminho da URL atual é comparado. Atual, nesse contexto, significa o valor do caminho da URL quando a regra é aplicada. Se alguma regra antecedeu a regra atual, ela pode ter correspondido à URL solicitada originalmente 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 reescrita".

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

Sintaxe de padrões de regras

A sintaxe de 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:

Sintaxe de expressão regular compatível com ECMAScript – Compatível com Perl (compatível com padrão ECMAScript). Essa é 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. Veja a seguir um exemplo de um padrão neste formato: "/Scripts/*_in.???", em que asterisco ("*") significa "corresponder a qualquer número de caracteres e capturá-los em uma referência de fundo" e "?" significa corresponder exatamente a um caractere (nenhuma referência de fundo é 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ões que não diferencia maiúsculas de minúsculas é usada. Para habilitar a sensibilidade a 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 regra, 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 de regra são avaliadas depois que a correspondência de padrão de regra é bem-sucedida.

As condições são definidas dentro de uma coleção <conditions> de uma regra de reescrita. 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 de regra será executada somente se o padrão de regra for correspondido e:

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

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 a padrões de condição anteriores e/ou a padrões de regra.

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 da condição. Esse tipo de correspondência só pode ser usado 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 da condição. Esse tipo de correspondência só pode ser usado 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 é correspondida com um padrão de expressão regular. Um padrão de condição pode ser especificado usando a sintaxe de expressão regular ou usando a 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:

    • padrão – use esse atributo para especificar o padrão real.
    • ignoreCase – Use esse atributo para controlar se a correspondência de padrões para a condição deve ser sensível ou insensível a maiúsculas e 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 reescrita é executada quando a URL atual corresponde ao padrão de regra e a avaliação da condição foi bem-sucedida (dependendo da configuração da regra, todas as condições correspondidas ou qualquer uma ou mais das condições correspondentes). Há vários tipos de ações disponíveis e o atributo de tipo 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 reescrita

Uma ação de reescrita 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 têm suporte no IIS.

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

  • url – Essa é 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 cruzadas para padrões de condição e regra. (Para obter mais informações, consulte a seção sobre como usar retro-referências.)
    • 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á considerado VERDADEIRO. Isso significa que a cadeia de caracteres de consulta da URL original é acrescentada à URL substituída.

Ação de redirecionamento

Uma ação de redirecionamento instrui o Módulo de Reescrita 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 um dos seguintes formulários:

  • Caminho de URL relativo – 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 a execução do redirecionamento.

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 de back-reference para os padrões de condição e regra. (Para obter mais informações, consulte a seção sobre como usar referências inversas.)
    • 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á considerado VERDADEIRO. Isso significa que a cadeia de caracteres de consulta da URL original é acrescentada à URL substituída.

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

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

    Observação

    O código de status HTTP 308 (Redirecionamento Permanente) não é compatível com o módulo regravação de URL.

Ação CustomResponse

Uma ação CustomResponse faz com que o Módulo de Reescrita de URL responda ao cliente HTTP usando um código de status, um subcódigo e um 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 remova a conexão HTTP da solicitação atual. A ação não tem parâmetros. O uso dessa ação implica que nenhuma regra subsequente é avaliada para a URL atual depois que essa ação é executada.

Nenhuma ação

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

Usando variáveis de servidor em regras de reescrita

As variáveis de servidor fornecem informações adicionais sobre as solicitações HTTP atuais. Você pode usar essas informações para tomar decisões de reescrita 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 regra, especificamente:

    • atributo url da ação de Reescrita e da ação de Redirecionamento
    • 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]+)" />

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 reescrita, você pode usar a variável de servidor {HTTP_USER_AGENT}.

Usando referências inversas em regras de reescrita

Partes de regras ou entradas de condições podem ser capturadas em referências de back-reference. Em seguida, eles podem ser usados para construir URLs de substituição em ações de regras ou para construir cadeias de caracteres de entrada para condições de regra.

As retro-referências 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 back pode ser criada colocando parênteses em torno da parte do padrão que deve capturar a referência de fundo. Por exemplo, o padrão ([0-9]+)/([a-z]+).html capturará 07 e artigo em referências de back desta URL solicitada: 07/article.html. Quando a sintaxe de padrão "Curinga" é usada, sempre são criadas referências de retorno quando um símbolo de asterisco (*) é usado no padrão. Nenhuma referência é criada quando "?" é usado no padrão. Por exemplo, o padrão */*.html capturará contoso e test nas back-references desta URL solicitada: contoso/test.html.

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

  • Cadeias de caracteres de entrada em condição

  • Em ações de regra, especificamente:

    • atributo url da ação de reescrita e redirecionamento
    • statusLine e responseLine de uma ação CustomResponse

  • Em um parâmetro de chave para o mapa de reescrita

Referências reversas a padrões de condição são identificadas por {C:N}, onde N varia de 0 a 9. As referências de back-reference aos padrões de regra são identificadas por {R:N} em que N é de 0 a 9. Observe que, para ambos os tipos de referências retrospectivas, {R:0} e {C:0}, conterão a string correspondente encontrada.

Por exemplo, neste padrão:

^(www\.)(.*)$

Para a cadeia de caracteres: www.foo.com, as retro-referências serão indexadas da seguinte maneira:

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

Dentro de uma ação de regra, você pode usar as retro-referências para o padrão da regra e para a última condição correspondida dessa regra. Dentro de uma string de condição, você pode usar as retro-referências para o padrão de regra e para a condição correspondente anterior.

O exemplo de regra a seguir demonstra como as retro-referências são criadas e utilizadas:

<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 gerencia o comportamento do cache de saída do IIS com o objetivo de:

  1. Utilize de forma ideal 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 Reescrita de URL.
  2. Impedir o cache de respostas, quando a lógica de cache pode ser violada devido à reescrita de URL.

O módulo controla o cache de saída alterando determinadas propriedades de cache ou desabilitando completamente o cache. O módulo não poderá habilitar o cache de saída se ele 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 leva em conta a URL original para construir uma chave para a entrada de cache.

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

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

    • "CACHE_URL"
    • "DOCUMENT_ROOT"
    • "HTTP_URL"
    • "HTTP_HOST"
    • INFORMAÇÃO_DO_CAMINHO
    • Caminho_Traduzido
    • "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 regra de reescrita usar qualquer variável de servidor não mencionada na lista acima, o conjunto de regras será considerado não seguro para o cache de saída. Isso significa que o Módulo de Reescrita de URL desabilitará o cache do modo kernel para todas as solicitações se as URLs de solicitação foram reescritas ou não. Além disso, o módulo alterará a política de cache do modo de usuário definindo a propriedade de cache varyByValue para conter a cadeia de caracteres concatenada de todos os valores das variáveis de servidor usados no conjunto de regras.

Funções de cadeia de caracteres

Há três funções de string disponíveis para alterar os valores dentro de uma ação de regra de reescrita, assim como quaisquer condições.

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

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

{function_name:any_string}

Onde "function_name" pode ser uma das seguintes: "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 de back-reference. 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 reescrita:

  • Cadeias de caracteres de entrada em condição

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

    • atributo url de ações de reescrita e redirecionamento
    • atributos statusLine e responseLine 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>

Reescrever mapas

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

Um mapa de reescrita 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 reescrita é identificado exclusivamente por seu nome e pode conter zero ou mais entradas chave-valor. Além disso, um mapa de reescrita 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 reescrita em qualquer nível de configuração, exceto no nível do arquivo. Os mapas de reescrita estão localizados dentro <do elemento de coleção rewriteMaps> .

Os mapas de reescrita são referenciados dentro de uma regra de reescrita 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 back-reference a padrões de regra ou condição. Por exemplo, os seguintes são usos válidos de um mapa de reescrita:

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

Uma referência a um mapa de reescrita é substituída pelo valor obtido ao usar a chave passada como parâmetro dentro da referência ao mapa de reescrita. Se uma chave não tiver sido encontrada, o valor padrão desse mapa de reescrita será usado.

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

  • Cadeia de caracteres de entrada condicional

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

    • atributo url de ações de reescrita e redirecionamento
    • statusLine e responseLine de ações CustomResponse

Exemplo 1: com um mapa de reescrita 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 maneira:

<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 reescrita não contém um elemento com key="/default.aspx"; portanto, o mapa de reescrita 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 reescrita 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 maneira:

<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 reescrita não contém um elemento com key="/default.aspx"; portanto, o mapa de reescrita 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.