URL Rewrite Module Configuration Reference (Guida di riferimento per la configurazione di URL Rewrite Module)

di Ruslan Kashšev

Questo articolo offre una panoramica del modulo di riscrittura URL e illustra i concetti di configurazione usati dal modulo.

Panoramica delle funzionalità

Il modulo di riscrittura URL riscrive gli URL delle richieste in indirizzi semplici, descrittivi e descrittivi del motore di ricerca visualizzati agli utenti o nelle applicazioni Web. La riscrittura URL usa regole definite per valutare e quindi eseguire il mapping dell'URL della richiesta all'indirizzo definito nella regola prima dell'elaborazione da parte di un server Web IIS. È possibile definire la logica di riscrittura url che include espressioni regolari e caratteri jolly e le regole possono essere applicate in base all'URL della richiesta, alle intestazioni HTTP e alle variabili del server. Anche se lo scopo principale del modulo è riscrivere gli URL delle richieste in URL più descrittivi, è anche possibile usare il modulo per definire regole che eseguono reindirizzamenti, inviare risposte personalizzate o interrompere le richieste.

Panoramica delle regole di riscrittura

Una regola di riscrittura definisce la logica di cosa confrontare o confrontare l'URL della richiesta con e cosa fare se il confronto ha esito positivo.

Le regole di riscrittura sono costituite dalle parti seguenti:

• Pattern : il modello di regola viene usato per specificare l'espressione regolare o un criterio con caratteri jolly usato per trovare le corrispondenze con le stringhe URL.
• Condizioni : la raccolta di condizioni facoltative viene usata per specificare operazioni logiche aggiuntive da eseguire se una stringa URL corrisponde al modello di regola. Nelle condizioni è possibile verificare la presenza di determinati valori di intestazioni HTTP o variabili del server oppure verificare se l'URL richiesto corrisponde a un file o a una directory in un file system fisico.
• Azione : l'azione viene usata per specificare cosa fare se la stringa URL corrisponde al modello di regola e vengono soddisfatte tutte le condizioni della regola.

Riscrivere l'ambito delle regole

Le regole di riscrittura possono essere definite in due raccolte diverse:

• <globalRules> : le regole in questa raccolta possono essere definite solo a livello di server. Le regole globali vengono usate per definire la logica di riscrittura url a livello di server. Queste regole vengono definite all'interno del file ApplicationHost.config e non possono essere sottoposte a override o disabilitate su livelli di configurazione inferiori. Le regole globali operano sempre sul percorso dell'URL assoluto, ovvero l'URI richiesto senza il nome del server. Queste regole vengono valutate nelle prime fasi della pipeline di elaborazione delle richieste IIS (evento PreBeginRequest ).
• <rules> : le regole in questa raccolta sono denominate regole distribuite e possono essere definite a qualsiasi livello nella gerarchia di configurazione. Le regole distribuite vengono usate per definire la logica di riscrittura URL specifica per un ambito di configurazione specifico. Questo tipo di regola può essere aggiunto a qualsiasi livello di configurazione usando file Web.config o usando <location> tag all'interno di file ApplicationHost.config o Web.config. Le regole distribuite operano sul percorso URL, in relazione al percorso del file Web.config in cui sono definite. Nei casi in cui le regole distribuite sono definite all'interno di un <location> tag, operano sul percorso URL, rispetto al percorso specificato per tale <location> tag. Queste regole vengono valutate nell'evento BeginRequest nella pipeline IIS.

Valutazione delle regole

Ogni livello di configurazione in IIS può avere zero o più regole di riscrittura definite. Le regole vengono valutate nello stesso ordine in cui vengono specificate. Il modulo di riscrittura URL elabora il set di regole usando l'algoritmo seguente:

1. In primo luogo, l'URL viene confrontato con il modello di una regola. Se non corrisponde, il modulo di riscrittura URL interrompe immediatamente l'elaborazione della regola e passa alla regola successiva.
2. Se un criterio corrisponde e non sono presenti condizioni per la regola, il modulo di riscrittura URL esegue l'azione specificata per questa regola e quindi passa alla regola successiva, dove usa l'URL sostituito come input per tale regola.
3. Se un criterio corrisponde e sono presenti condizioni per la regola, il modulo di riscrittura URL valuta le condizioni. Se la valutazione ha esito positivo, viene eseguita l'azione della regola specificata e quindi l'URL riscritto viene usato come input per la regola successiva

Una regola può avere il flag StopProcessing attivato. Quando viene eseguita l'azione della regola (ad esempio la regola corrispondente) e questo flag viene attivato, significa che non verranno elaborate altre regole successive e la richiesta verrà passata alla pipeline di richiesta IIS. Per impostazione predefinita, questo flag è disattivato.

Ereditarietà delle regole

Se le regole sono definite su più livelli di configurazione, il modulo di riscrittura URL valuta le regole nell'ordine seguente:

1. Valutare tutte le regole globali.
2. Valutare un set di regole che include regole distribuite dai livelli di configurazione padre, nonché regole dal livello di configurazione corrente. La valutazione viene eseguita in un ordine padre-figlio, il che significa che le regole padre vengono valutate per prime e le regole definite in un ultimo livello figlio vengono valutate per ultimo.

Mantenimento dell'URL originale

Il modulo di riscrittura URL mantiene il percorso URL richiesto originale nelle variabili del server seguenti:

• HTTP_X_ORIGINAL_URL: questa variabile server contiene l'URL originale in formato decodificato;
• UNENCODED_URL: questa variabile server contiene l'URL originale esattamente come richiesto da un client Web, con tutte le codifiche originali mantenute.

Accesso alle parti URL da una regola di riscrittura

È importante comprendere come è possibile accedere a determinate parti della stringa URL da una regola di riscrittura.

Per un URL HTTP in questo formato: http(s)://<host>:<port>/<path>?<Querystring>

• Il <percorso> viene confrontato con il modello della regola.
• La <querystring> è disponibile nella variabile server denominata QUERY_STRING ed è accessibile usando una condizione all'interno di una regola.
• L'host <> è disponibile nella variabile server HTTP_HOST ed è accessibile usando una condizione all'interno di una regola.
• La <porta> è disponibile nella variabile server edizione Standard RVER_PORT ed è accessibile usando una condizione all'interno di una regola.
• Le variabili del server edizione Standard RVER_PORT_edizione Standard CURE e HTTPS possono essere usate per determinare se è stata usata una connessione sicura. È possibile accedere a queste variabili del server usando una condizione all'interno di una regola.
• La variabile server REQUEST_URI può essere usata per accedere all'intero percorso URL richiesto, inclusa la stringa di query.

Ad esempio, se è stata effettuata una richiesta per questo URL: http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3e una regola di riscrittura è stata definita a livello di sito, allora:

• Il modello di regola ottiene la stringa content/default.aspx URL come input.
• La variabile server QUERY_STRING contiene tabid=2&subtabid=3.
• La variabile server HTTP_HOST contiene www.mysite.com.
• La variabile server edizione Standard RVER_PORT contiene 80.
• La variabile server edizione Standard RVER_PORT_edizione Standard CURE contiene 0 e HTTPS contiene OFF.
• La variabile server REQUEST_URI contiene /content/default.aspx?tabid=2&subtabid=3.
• La variabile server PATH_INFO contiene /content/default.aspx.

Si noti che la stringa dell'URL di input passata a una regola distribuita è sempre relativa al percorso del file Web.config in cui è definita la regola. Ad esempio, se viene effettuata una richiesta per http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3e viene definita una regola di riscrittura nella directory /content , la regola ottiene questa stringa URL default.aspx come input.

Riscrivere la configurazione delle regole

Modello di regola

Viene usato un modello di regola di riscrittura per specificare un modello a cui viene confrontato il percorso URL corrente. Corrente, in questo contesto, indica il valore del percorso URL quando viene applicata la regola. Se sono presenti regole che hanno preceduto la regola corrente, potrebbero avere corrispondenze con l'URL richiesto originale e modificarlo. La stringa URL valutata rispetto al modello non include la stringa di query. Per includere la stringa di query nella valutazione della regola, è possibile usare la variabile server QUERY_STRING nella condizione della regola. Per altre informazioni, vedere "Uso delle variabili del server nelle regole di riscrittura".

Un criterio viene specificato all'interno di un <elemento match> di una regola di riscrittura.

Sintassi dei criteri di regola

È possibile specificare la sintassi dei criteri di regola usando l'attributo patternSyntax di una regola. Questo attributo può essere impostato su una delle opzioni seguenti:

ECMAScript : sintassi delle espressioni regolari compatibili con ECMAScript (conforme allo standard ECMAScript). Si tratta di un'opzione predefinita per qualsiasi regola. Questo è un esempio del formato del modello: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Carattere jolly: sintassi con caratteri jolly usata nel modulo di reindirizzamento HTTP IIS. Di seguito è riportato un esempio di modello in questo formato: "/Scripts/*_in.???", dove l'asterisco ("*") indica "corrisponde a un numero qualsiasi di caratteri e li acquisisce in un back-reference" e "?" indica esattamente un carattere (non viene creato alcun back-reference).

L'ambito dell'attributo patternSyntax è per regola, vale a dire che si applica al modello della regola corrente e a tutti i modelli usati nelle condizioni di tale regola.

Proprietà dei criteri di regola

Un criterio può essere negato usando l'attributo negate dell'elemento <match> . Quando viene usato questo attributo, l'azione della regola viene eseguita solo se l'URL corrente non corrisponde al modello specificato.

Per impostazione predefinita, vengono usati criteri di ricerca senza distinzione tra maiuscole e minuscole. Per abilitare la distinzione tra maiuscole e minuscole, è possibile usare l'attributo ignoreCase dell'elemento <match> della regola.

Condizioni per le regole

Le condizioni delle regole consentono di definire logica aggiuntiva per la valutazione delle regole, che può essere basata su input diversi da una sola stringa url corrente. Qualsiasi regola può avere zero o più condizioni. Le condizioni delle regole vengono valutate dopo che la corrispondenza del criterio di regola ha esito positivo.

Le condizioni vengono definite all'interno di una <raccolta di condizioni> di una regola di riscrittura. Questa raccolta ha un attributo denominato logicalGrouping che controlla la modalità di valutazione delle condizioni. Se una regola presenta condizioni, l'azione della regola viene eseguita solo se il modello di regola viene confrontato e:

• Tutte le condizioni sono state valutate come true, purché sia stato usato logicalGrouping="MatchAll".
• Almeno una delle condizioni è stata valutata come true, purché sia stato usato logicalGrouping="MatchAny".

Una condizione viene definita specificando le proprietà seguenti:

• Stringa di input
• Tipo di corrispondenza

L'input della condizione specifica l'elemento da utilizzare come input per la valutazione della condizione. L'input della condizione è una stringa arbitraria che può includere variabili server e riferimenti back-reference ai modelli di condizione precedenti e/o ai modelli di regola.

Il tipo di corrispondenza può essere una delle tre opzioni seguenti:

• IsFile : questo tipo di corrispondenza viene usato per determinare se la stringa di input contiene un percorso fisico di un file in un file system. Se non viene specificata una stringa di input della condizione, il modulo di riscrittura URL usa il percorso fisico del file richiesto come valore predefinito per l'input della condizione. Questo tipo di corrispondenza può essere usato solo per le regole distribuite.

• IsDirectory : questo tipo di corrispondenza viene usato per determinare se la stringa di input contiene un percorso fisico di una directory in un file system. Se non viene specificata una stringa di input della condizione, il modulo di riscrittura URL usa il percorso fisico del file richiesto come valore predefinito per l'input della condizione. Questo tipo di corrispondenza può essere usato solo per le regole distribuite.

• Pattern: questo tipo di corrispondenza viene usato per esprimere una condizione in cui una stringa di input arbitraria viene confrontata con un criterio di espressione regolare. È possibile specificare un criterio di condizione usando la sintassi delle espressioni regolari o la sintassi con caratteri jolly. Il tipo di criterio da usare in una condizione dipende dal valore del flag patternSyntax definito per la regola a cui appartiene questa condizione. Questo tipo di condizione ha due attributi correlati che controllano i criteri di ricerca:

  • pattern : usare questo attributo per specificare il modello effettivo.
  • ignoreCase : usare questo attributo per controllare se i criteri di ricerca per la condizione devono fare distinzione tra maiuscole e minuscole o senza distinzione tra maiuscole e minuscole.

Inoltre, il risultato della valutazione della condizione può essere negato usando l'attributo negate . Può essere usato per specificare una condizione che controlla se l'URL richiesto non è un file, come nell'esempio seguente:

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

Azione regola

Un'azione di riscrittura della regola viene eseguita quando l'URL corrente corrisponde al modello di regola e la valutazione della condizione ha avuto esito positivo (a seconda della configurazione della regola, tutte le condizioni corrispondono o una o più delle condizioni corrispondenti). Sono disponibili diversi tipi di azioni e l'attributo type dell'elemento di configurazione dell'azione <> può essere usato per specificare l'azione eseguita dalla regola. Le sezioni seguenti descrivono diversi tipi di azione e le opzioni di configurazione correlate a tipi di azione specifici.

Azione di riscrittura

Un'azione Riscrittura sostituisce la stringa URL corrente con una stringa di sostituzione. Una stringa di sostituzione deve sempre specificare il percorso URL, ad esempio contoso/test/default.aspx. Si noti che le sostituzioni che contengono un percorso fisico in un file system (ad esempio, C:\inetpub\wwwroot) non sono supportate in IIS.

Un'azione Riscrittura include le opzioni di configurazione seguenti:

• url : stringa di sostituzione da usare per la riscrittura dell'URL corrente. L'URL di sostituzione è un valore stringa che può includere quanto segue:

  • Riferimenti di back-reference ai modelli di condizione e regola. Per altre informazioni, vedere la sezione relativa all'uso di back-references.
  • Variabili del server. Per altre informazioni, vedere la sezione relativa all'uso delle variabili del server.

• appendQueryString : specifica se la stringa di query dall'URL corrente viene mantenuta durante la sostituzione. Per impostazione predefinita, se il valore del flag appendQueryString non viene specificato, si presuppone che sia TRUE. Ciò significa che la stringa di query dall'URL originale viene aggiunta all'URL sostituito.

Azione di reindirizzamento

Un'azione di reindirizzamento indica al modulo di riscrittura URL per inviare una risposta di reindirizzamento al client. Il codice di stato di reindirizzamento (3xx) può essere specificato come parametro per questa azione. Il campo Location della risposta contiene la stringa di sostituzione specificata nella regola.

L'URL di sostituzione per la regola di reindirizzamento può essere specificato in uno dei formati seguenti:

• Percorso URL relativo : contoso/test/default.aspx
• URI assoluto : https://example.com/contoso/test/default.aspx

L'utilizzo di un'azione di reindirizzamento implica che nessuna regola successiva valutata per l'URL corrente dopo l'esecuzione del reindirizzamento.

Per un'azione di reindirizzamento sono disponibili le opzioni di configurazione seguenti:

• url : usa una stringa di sostituzione come URL di reindirizzamento. Un URL di sostituzione è una stringa che può includere quanto segue:

  • Riferimenti di back-reference ai modelli di condizione e regola. Per altre informazioni, vedere la sezione relativa all'uso di back-references.
  • Variabili del server. Per altre informazioni, vedere la sezione relativa all'uso delle variabili del server.

• appendQueryString : specifica se la stringa di query dall'URL corrente deve essere mantenuta durante la sostituzione. Per impostazione predefinita, se il flag AppendQueryString non è specificato, si presuppone che sia TRUE. Ciò significa che la stringa di query dall'URL originale viene aggiunta all'URL sostituito.

• redirectType : specifica il codice di stato da usare durante il reindirizzamento:

  • 301 – Permanente
  • 302 - Trovato
  • 303 - Vedere altri
  • 307 – Temporaneo

Azione CustomResponse

Un'azione CustomResponse fa sì che il modulo di riscrittura URL risponda al client HTTP usando un codice di stato, un codice secondario e un motivo specificati dall'utente. L'uso di un'azione CustomResponse implica che nessuna regola successiva viene valutata per l'URL corrente dopo l'esecuzione di questa azione.

L'azione CustomResponse include le opzioni di configurazione seguenti:

• statusCode: specifica il codice di stato da usare in risposta al client.
• subStatusCode : specifica il codice dello stato secondario da usare in risposta al client.
• statusReason : specifica la frase motivo da usare con il codice di stato.
• statusDescription : specifica la descrizione di una riga da inserire nel corpo della risposta.

Azione AbortRequest

Un'azione AbortRequest fa sì che il modulo di riscrittura URL rilasci la connessione HTTP per la richiesta corrente. L'azione non include parametri. L'uso di questa azione implica che nessuna regola successiva viene valutata per l'URL corrente dopo l'esecuzione di questa azione.

Nessuna azione

Viene utilizzata un'azione Nessuno per specificare che non viene eseguita alcuna azione.

Uso delle variabili del server nelle regole di riscrittura

Le variabili del server forniscono informazioni aggiuntive sulle richieste HTTP correnti. È possibile usare queste informazioni per prendere decisioni di riscrittura o per comporre l'URL riscritto. È possibile fare riferimento alle variabili del server nelle posizioni seguenti all'interno delle regole di riscrittura:

• Nella stringa di input della condizione

• Nelle stringhe di sostituzione delle regole, in particolare:

  • attributo url dell'azione Riscrittura e reindirizzamento
  • statusLine e responseLine di un'azione CustomResponse

È possibile fare riferimento alle variabili del server usando la sintassi {VARIABLE_NAME}. Ad esempio, la condizione seguente usa la variabile server QUERY_STRING:

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

Le variabili del server possono essere usate anche per accedere alle intestazioni HTTP dalla richiesta corrente. Qualsiasi intestazione HTTP fornita dalla richiesta corrente è rappresentata come variabile server con un nome generato in base a questa convenzione di denominazione:

1. Tutti i simboli trattini ("-") nel nome dell'intestazione HTTP vengono convertiti in simboli di sottolineatura ("_").
2. Tutte le lettere nel nome dell'intestazione HTTP vengono convertite in maiuscolo.
3. Il prefisso "HTTP_" viene aggiunto al nome dell'intestazione.

Ad esempio, per accedere all'intestazione HTTP "user-agent" da una regola di riscrittura, è possibile usare la variabile server {HTTP_U edizione Standard R_AGENT}.

Uso dei riferimenti in regole di riscrittura

Le parti degli input di regole o condizioni possono essere acquisite nei riferimenti back-reference. Questi possono quindi essere usati per costruire URL di sostituzione all'interno di azioni regole o per costruire stringhe di input per le condizioni delle regole.

I back-reference vengono generati in modi diversi, a seconda del tipo di sintassi del criterio usato per la regola. Quando viene usata una sintassi del modello ECMAScript, è possibile creare un back-reference inserendo parentesi intorno alla parte del modello che deve acquisire il back-reference. Ad esempio, il modello ([0-9]+)/([a-z]+).html acquisirà 07 e l'articolo nei riferimenti back-reference da questo URL richiesto: 07/article.html. Quando si usa la sintassi del modello "Carattere jolly", i riferimenti back-reference vengono sempre creati quando viene usato un simbolo asterisco (*) nel modello. Non vengono creati riferimenti in caso di utilizzo di "?" nel modello. Ad esempio, il modello */*.html acquisisce contoso e testa i riferimenti back-reference da questo URL richiesto: contoso/test.html.

L'utilizzo dei back-reference è lo stesso indipendentemente dalla sintassi del modello usata per acquisire tali riferimenti. I riferimenti back-reference possono essere usati nelle posizioni seguenti all'interno delle regole di riscrittura:

• Nelle stringhe di input della condizione

• Nelle azioni delle regole, in particolare:

  • attributo url dell'azione Riscrittura e reindirizzamento
  • statusLine e responseLine di un'azione CustomResponse

• In un parametro chiave per la mappa di riscrittura

I riferimenti back-reference ai modelli di condizione vengono identificati da {C:N} dove N è compreso tra 0 e 9. I back-reference ai modelli di regola sono identificati da {R:N} dove N è compreso tra 0 e 9. Si noti che per entrambi i tipi di back-reference, {R:0} e {C:0}, conterrà la stringa corrispondente.

Ad esempio, in questo modello:

^(www\.)(.*)$

Per la stringa: www.foo.com i back-reference verranno indicizzati come segue:

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

All'interno di un'azione regola, è possibile usare i riferimenti back-reference al modello di regola e all'ultima condizione corrispondente di tale regola. All'interno di una stringa di input della condizione, è possibile usare i riferimenti back-reference al modello di regola e alla condizione corrispondente in precedenza.

Nell'esempio di regola seguente viene illustrato come vengono creati e a cui si fa riferimento i riferimenti ai riferimenti:

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

Interazione con la memorizzazione nella cache dell'output iis

Il modulo di riscrittura URL controlla il comportamento della cache di output IIS per:

1. Utilizzare in modo ottimale la modalità kernel e la memorizzazione nella cache dell'output in modalità utente delle risposte per gli URL riscritti, migliorando così le prestazioni dell'applicazione Web che usa il modulo di riscrittura URL.
2. Impedire la memorizzazione nella cache delle risposte, quando la logica di memorizzazione nella cache può essere violata a causa della riscrittura dell'URL.

Il modulo controlla la memorizzazione nella cache dell'output modificando determinate proprietà di memorizzazione nella cache o disabilitando completamente la memorizzazione nella cache. Il modulo non può abilitare la memorizzazione nella cache dell'output se è stata disabilitata dalla configurazione IIS o da qualsiasi altro modulo nella pipeline IIS. La memorizzazione nella cache dell'output viene controllata come segue:

1. Il modulo imposta sempre l'impostazione della cache in modalità utente varyByHeader="HTTP_X_ORIGINAL_URL". In questo modo, quando la memorizzazione nella cache in modalità utente è abilitata, il modulo prende in considerazione l'URL originale per costruire una chiave per la voce della cache.

2. Se un set di regole di riscrittura usa variabili server con valori costanti per tutta la durata del processo o derivati dall'URL richiesto, il set di regole viene considerato sicuro per la memorizzazione nella cache dell'output. Ciò significa che il modulo di riscrittura URL non modifica i criteri di memorizzazione nella cache esistenti in alcun modo diverso dall'impostazione varyByHeader come descritto nel passaggio 1.

   Le variabili server seguenti, se usate nelle regole di riscrittura, non influiscono sui criteri di memorizzazione nella cache dell'output:

   • "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"
   • "edizione Standard RVER_SOFTWARE"
   • "SSI_EXEC_DISABLED"

3. Se un set di regole di riscrittura usa qualsiasi variabile server non menzionata nell'elenco precedente, il set di regole viene considerato non sicuro per la memorizzazione nella cache dell'output. Ciò significa che il modulo di riscrittura URL disabiliterà la memorizzazione nella cache in modalità kernel per tutte le richieste, indipendentemente dal fatto che gli URL della richiesta siano stati riscritti o meno. Inoltre, il modulo modificherà i criteri di memorizzazione nella cache per la cache in modalità utente impostando la proprietà di memorizzazione nella cache varyByValue in modo da contenere la stringa concatenata di tutti i valori delle variabili server usate nel set di regole.

Funzioni di stringa

Sono disponibili tre funzioni stringa per la modifica dei valori all'interno di un'azione regola di riscrittura, nonché per qualsiasi condizione:

• ToLower : restituisce la stringa di input convertita in lettere minuscole.
• UrlEncode : restituisce la stringa di input convertita in formato con codifica URL. Questa funzione può essere usata se l'URL di sostituzione nella regola di riscrittura contiene caratteri speciali ( ad esempio caratteri non ASCII o non sicuri URI).
• UrlDecode : decodifica la stringa di input con codifica URL. Questa funzione può essere usata per decodificare un input di condizione prima di associarlo a un modello.

Le funzioni possono essere richiamate usando la sintassi seguente:

{function_name:any_string}

Dove "function_name" può trovarsi in eof the following: "ToLower", "UrlEncode", "UrlDecode". "Any_string" può essere una stringa letterale o una stringa compilata usando variabili server o back-reference. Ad esempio, di seguito sono riportate chiamate valide di funzioni stringa:

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

Le funzioni stringa possono essere usate nelle posizioni seguenti all'interno delle regole di riscrittura:

• Nelle stringhe di input della condizione

• Nelle stringhe di sostituzione delle regole, in particolare:

  • attributo url delle azioni Di riscrittura e reindirizzamento
  • attributi statusLine e responseLine di un'azione CustomResponse

Esempio di regola che usa la funzione 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>

Esempio di regola che usa la funzione UrlEncode :

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

Esempio di regola che usa la funzione 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>

Riscrivere le mappe

Una mappa di riscrittura è una raccolta arbitraria di coppie nome-valore che possono essere usate all'interno di regole di riscrittura per generare l'URL di sostituzione durante la riscrittura. Le mappe di riscrittura sono particolarmente utili quando si dispone di un ampio set di regole di riscrittura e tutte queste regole usano stringhe statiche, ovvero quando non viene usata alcuna corrispondenza di criteri. In questi casi, invece di definire un ampio set di regole di riscrittura semplici, è possibile inserire tutti i mapping nella mappa di riscrittura come chiavi e valori tra l'URL di input e l'URL di sostituzione. Quindi, per cercare l'URL di sostituzione in base all'URL di input, si avrà una regola di riscrittura che fa riferimento alla mappa di riscrittura.

Una mappa di riscrittura definisce una raccolta denominata di stringhe di coppie nome-valore, come nell'esempio seguente:

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

Una mappa di riscrittura viene identificata in modo univoco dal nome e può contenere zero o più voci chiave-valore. Inoltre, una mappa di riscrittura può specificare il valore predefinito da usare quando non viene trovata una chiave. Questo controllo viene controllato tramite l'attributo defaultValue . Per impostazione predefinita, una stringa vuota viene usata come valore predefinito.

È possibile riscrivere le mappe in qualsiasi livello di configurazione, ad eccezione del livello di file. Le mappe di riscrittura si trovano all'interno della <riscrittura Mappe> elemento raccolta.

Le mappe di riscrittura vengono referenziate all'interno di una regola di riscrittura usando la sintassi seguente:

{RewriteMapName:Key}

Dove il parametro Key può essere qualsiasi stringa arbitraria e può includere riferimenti back-reference a criteri di regola o condizione. Ad esempio, di seguito sono riportati gli usi validi di una mappa di riscrittura:

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

Un riferimento a una mappa di riscrittura viene sostituito con il valore cercato usando la chiave passata come parametro all'interno di un riferimento alla mappa di riscrittura. Se non è stata trovata una chiave, viene usato il valore predefinito per la mappa di riscrittura.

È possibile fare riferimento a una mappa di riscrittura nelle posizioni seguenti all'interno delle regole di riscrittura:

• Nella stringa di input della condizione

• Nelle stringhe di sostituzione delle regole, in particolare:

  • attributo url delle azioni Di riscrittura e reindirizzamento
  • statusLine e responseLine delle azioni CustomResponse

Esempio 1: con una mappa di riscrittura definita come segue:

<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 una regola di riscrittura definita come segue:

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

L'URL richiesto /diagnostic verrà riscritto come /default.aspx?tabid=2&subtabid=29.
L'URL richiesto /webcasts verrà riscritto in /default.aspx?tabid=2&subtabid=24.
L'URL richiesto /php verrà riscritto in /default.aspx?tabid=7116.
L'URL richiesto /default.aspx non verrà riscritto perché la mappa di riscrittura non contiene un elemento con key="/default.aspx"; di conseguenza, la mappa di riscrittura restituirà una stringa vuota che non corrisponderà al modello di condizione, pertanto l'azione della regola non verrà eseguita.

Esempio 2: con una mappa di riscrittura definita come segue:

<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 una regola di riscrittura definita come segue:

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

L'URL richiesto /default.aspx?tabid=2&subtabid=29 verrà reindirizzato a http://www.contoso.com/diagnostics.
L'URL richiesto /default.aspx?tabid=2&subtabid=24 verrà reindirizzato a http://www.contoso.com/webcasts.
L'URL richiesto /default.aspx?tabid=7116 verrà reindirizzato a http://www.contoso.com/php.
L'URL richiesto /default.aspx non verrà reindirizzato perché la mappa di riscrittura non contiene un elemento con key="/default.aspx"; pertanto, la mappa di riscrittura restituirà una stringa vuota che non corrisponderà al modello di condizione, pertanto l'azione della regola non verrà eseguita.