Freigeben über

URL Rewrite Module Configuration Reference (Konfigurationsreferenz für das URL-Umschreibungsmodul)

  • Artikel

von Ruslan Yakushev

Dieser Artikel enthält eine Übersicht über das URL Rewrite Module und erläutert die Konfigurationskonzepte, die vom Modul verwendet werden.

Übersicht über die Funktionalität

Das URL Rewrite Module schreibt Anforderungs-URLs in einfache, benutzerfreundliche und suchmaschinenfreundliche Adressen um, die benutzern oder in Webanwendungen angezeigt werden. Url Rewrite verwendet definierte Regeln, um die Anforderungs-URL der in der Regel definierten Adresse zuzuordnen, bevor sie von einem IIS-Webserver verarbeitet wird. Sie können URL-Umschreibungslogik definieren, die reguläre Ausdrücke und Wild Karte enthält, und Regeln können basierend auf der Anforderungs-URL, HTTP-Headern und Servervariablen angewendet werden. Während der Hauptzweck des Moduls darin besteht, Anforderungs-URLs in benutzerfreundlichere URLs umzuschreiben, können Sie das Modul auch verwenden, um Regeln zu definieren, die Umleitungen ausführen, benutzerdefinierte Antworten senden oder Abbruchanforderungen durchführen.

Übersicht über neu geschriebene Regeln

Eine Umschreibregel definiert die Logik, mit der die Anforderungs-URL verglichen oder mit der Anforderungs-URL verglichen werden soll, und was zu tun ist, wenn der Vergleich erfolgreich ist.

Neuschreibregeln bestehen aus den folgenden Teilen:

  • Muster – Das Regelmuster wird verwendet, um entweder den regulären Ausdruck oder ein Wild Karte Muster anzugeben, das zum Abgleichen von URL-Zeichenfolgen verwendet wird.
  • Bedingungen – Die optionale Bedingungsauflistung wird verwendet, um zusätzliche logische Vorgänge anzugeben, die ausgeführt werden sollen, wenn eine URL-Zeichenfolge mit dem Regelmuster übereinstimmt. Innerhalb der Bedingungen können Sie nach bestimmten Werten von HTTP-Headern oder Servervariablen suchen oder überprüfen, ob die angeforderte URL einer Datei oder einem Verzeichnis in einem physischen Dateisystem entspricht.
  • Aktion – Die Aktion wird verwendet, um anzugeben, was zu tun ist, wenn die URL-Zeichenfolge mit dem Regelmuster übereinstimmt und alle Regelbedingungen erfüllt sind.

Regelnbereich neu schreiben

Regeln zum Umschreiben können in zwei verschiedenen Auflistungen definiert werden:

  • <globalRules> – Regeln in dieser Sammlung können nur auf Serverebene definiert werden. Globale Regeln werden verwendet, um serverweite URL-Umschreibungslogik zu definieren. Diese Regeln werden in der Datei "ApplicationHost.config" definiert und können nicht auf niedrigeren Konfigurationsebenen außer Kraft gesetzt oder deaktiviert werden. Globale Regeln werden immer auf dem Pfad der absoluten URL (d. a. der angeforderte URI ohne Servername) ausgeführt. Diese Regeln werden frühzeitig in der IIS-Anforderungsverarbeitungspipeline (PreBeginRequest-Ereignis ) ausgewertet.
  • <rules> – Regeln in dieser Sammlung werden als verteilte Regeln bezeichnet und können auf jeder Ebene in der Konfigurationshierarchie definiert werden. Verteilte Regeln werden verwendet, um spezielle URL-Umschreibungslogik für einen bestimmten Konfigurationsbereich zu definieren. Dieser Regeltyp kann auf jeder Konfigurationsebene mithilfe von Web.config-Dateien oder mithilfe <location> von Tags in ApplicationHost.config- oder Web.config-Dateien hinzugefügt werden. Verteilte Regeln werden auf dem URL-Pfad relativ zum Speicherort der Web.config-Datei ausgeführt, in der sie definiert sind. In Fällen, in denen verteilte Regeln innerhalb eines <location> Tags definiert sind, arbeiten sie auf dem URL-Pfad relativ zum für dieses <location> Tag angegebenen Pfad. Diese Regeln werden für das BeginRequest-Ereignis in der IIS-Pipeline ausgewertet.

Regelauswertung

Jede Konfigurationsstufe in IIS kann null oder mehr Neuschreibregeln definiert haben. Die Regeln werden in derselben Reihenfolge ausgewertet, in der sie angegeben werden. Das URL Rewrite Module verarbeitet den Satz von Regeln mithilfe des folgenden Algorithmus:

  1. Zunächst wird die URL mit dem Muster einer Regel abgeglichen. Wenn sie nicht übereinstimmen, beendet das URL Rewrite Module sofort die Verarbeitung dieser Regel und wechselt zur nächsten Regel.
  2. Wenn ein Muster übereinstimmt und es keine Bedingungen für die Regel gibt, führt das URL Rewrite Module die für diese Regel angegebene Aktion aus und wechselt dann zur nächsten Regel, wobei die ersetzte URL als Eingabe für diese Regel verwendet wird.
  3. Wenn ein Muster übereinstimmt und Bedingungen für die Regel vorhanden sind, wertet das URL Rewrite Module die Bedingungen aus. Wenn die Auswertung erfolgreich ist, wird die angegebene Regelaktion ausgeführt, und dann wird die umgeschriebene URL als Eingabe für die nachfolgende Regel verwendet.

Eine Regel hat möglicherweise das StopProcessing-Flag aktiviert. Wenn die Regelaktion ausgeführt wird (d. h. die Regel stimmt mit der Regel überein), und dieses Flag ist aktiviert, bedeutet dies, dass keine weiteren nachfolgenden Regeln verarbeitet werden und die Anforderung an die IIS-Anforderungspipeline übergeben wird. Diese Kennzeichnung ist standardmäßig deaktiviert.

Regelvererbung

Wenn Regeln auf mehreren Konfigurationsebenen definiert sind, wertet das URL Rewrite Module die Regeln in der folgenden Reihenfolge aus:

  1. Alle globalen Regeln auswerten.
  2. Wertet einen Regelsatz aus, der verteilte Regeln von übergeordneten Konfigurationsebenen sowie Regeln aus der aktuellen Konfigurationsstufe enthält. Die Auswertung erfolgt in einer Reihenfolge zwischen übergeordneten und untergeordneten Elementen. Dies bedeutet, dass die übergeordneten Regeln zuerst ausgewertet werden und die auf einer letzten untergeordneten Ebene definierten Regeln zuletzt ausgewertet werden.

Beibehalten der ursprünglichen URL

Das URL Rewrite Module behält den ursprünglich angeforderten URL-Pfad in den folgenden Servervariablen bei:

  • HTTP_X_ORIGINAL_URL – diese Servervariable enthält die ursprüngliche URL im decodierten Format;
  • UNENCODED_URL – diese Servervariable enthält die ursprüngliche URL genau so, wie sie von einem Webclient angefordert wurde, wobei alle ursprünglichen Codierungen erhalten bleiben.

Zugreifen auf URL-Webparts aus einer Neuschreibregel

Es ist wichtig zu verstehen, wie auf bestimmte Teile der URL-Zeichenfolge über eine Umschreibregel zugegriffen werden kann.

Für eine HTTP-URL in diesem Format: http(s)://<host>:<port>/<path>?<Querystring>

  • Der <Pfad> wird mit dem Muster der Regel abgeglichen.
  • Die <Abfragezeichenfolge> ist in der Servervariable namens QUERY_STRING verfügbar und kann mithilfe einer Bedingung innerhalb einer Regel aufgerufen werden.
  • Der <Host> ist in der Servervariablen HTTP_HOST verfügbar und kann mithilfe einer Bedingung innerhalb einer Regel aufgerufen werden.
  • Der <Port> ist in der Servervariablen SERVER_PORT verfügbar und kann mithilfe einer Bedingung innerhalb einer Regel aufgerufen werden.
  • Servervariablen SERVER_PORT_SECURE und HTTPS können verwendet werden, um zu ermitteln, ob eine sichere Verbindung verwendet wurde. Auf diese Servervariablen kann mithilfe einer Bedingung innerhalb einer Regel zugegriffen werden.
  • Die Servervariable REQUEST_URI kann verwendet werden, um auf den gesamten angeforderten URL-Pfad zuzugreifen, einschließlich der Abfragezeichenfolge.

Wenn beispielsweise eine Anforderung für diese URL gestellt wurde, http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3und eine Umschreibregel auf Websiteebene definiert wurde, dann:

  • Das Regelmuster ruft die URL-Zeichenfolge content/default.aspx als Eingabe ab.
  • Die QUERY_STRING Servervariable enthält tabid=2&subtabid=3.
  • Die HTTP_HOST Servervariable enthält www.mysite.com.
  • Die SERVER_PORT Servervariable enthält 80.
  • Die SERVER_PORT_SECURE Servervariable enthält 0 und HTTPS enthält OFF.
  • Die REQUEST_URI Servervariable enthält /content/default.aspx?tabid=2&subtabid=3.
  • Die PATH_INFO Servervariable enthält /content/default.aspx.

Beachten Sie, dass die an eine verteilte Regel übergebene Eingabe-URL-Zeichenfolge immer relativ zum Speicherort der Web.config-Datei ist, in der die Regel definiert ist. Wenn beispielsweise eine Anforderung gestellt http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3wird und eine Umschreibregel im Verzeichnis "/content " definiert ist, ruft die Regel diese URL-Zeichenfolge default.aspx als Eingabe ab.

Neuschreiben der Regelkonfiguration

Regelmuster

Ein Umschreibregelmuster wird verwendet, um ein Muster anzugeben, mit dem der aktuelle URL-Pfad verglichen wird. Current bedeutet in diesem Kontext den Wert des URL-Pfads, wenn die Regel angewendet wird. Wenn es Regeln gab, die der aktuellen Regel vorausgingen, stimmten sie möglicherweise mit der ursprünglich angeforderten URL überein und haben sie geändert. Die URL-Zeichenfolge, die anhand des Musters ausgewertet wird, enthält nicht die Abfragezeichenfolge. Um die Abfragezeichenfolge in die Regelauswertung einzuschließen, können Sie die servervariable QUERY_STRING in die Bedingung der Regel verwenden. Weitere Informationen finden Sie unter "Verwenden von Servervariablen in Neuschreibregeln".

Ein Muster wird innerhalb eines <Übereinstimmungselements> einer Neuschreibregel angegeben.

Regelmustersyntax

Die Regelmustersyntax kann mithilfe des PatternSyntax-Attributs einer Regel angegeben werden. Dieses Attribut kann auf eine der folgenden Optionen festgelegt werden:

ECMAScript – Perl-kompatible Reguläre Ausdruckssyntax (ECMAScript-Standardkonform) Dies ist eine Standardoption für jede Regel. Dies ist ein Beispiel für das Musterformat: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Wild Karte – Wild Karte Syntax, die im IIS-HTTP-Umleitungsmodul verwendet wird. Im Folgenden sehen Sie ein Beispiel für ein Muster in diesem Format: "/Scripts/*_in.???", wobei Sternchen ("*") "mit einer beliebigen Anzahl beliebiger Zeichen übereinstimmen und sie in einem Rückverweis erfassen" und "?" bedeutet, dass genau ein Zeichen übereinstimmt (kein Rückverweis wird erstellt).

Der Bereich des PatternSyntax-Attributs ist pro Regel, d. h. er gilt für das Muster der aktuellen Regel und für alle Muster, die in Bedingungen dieser Regel verwendet werden.

Regelmustereigenschaften

Ein Muster kann mithilfe des Negate-Attributs des <Match-Elements> negiert werden. Wenn dieses Attribut verwendet wird, wird die Regelaktion nur ausgeführt, wenn die aktuelle URL nicht mit dem angegebenen Muster übereinstimmt.

Standardmäßig wird der Musterabgleich zwischen Groß- und Kleinschreibung verwendet. Um die Groß-/Kleinschreibung zu aktivieren, können Sie das IgnoreCase-Attribut des <Übereinstimmungselements> der Regel verwenden.

Regelbedingungen

Regelbedingungen ermöglichen das Definieren zusätzlicher Logik für die Regelauswertung, die auf anderen Eingaben als nur einer aktuellen URL-Zeichenfolge basieren kann. Jede Regel kann null oder mehr Bedingungen aufweisen. Regelbedingungen werden ausgewertet, nachdem die Regelmustervergleich erfolgreich war.

Bedingungen werden in einer <Bedingungsauflistung> einer Neuschreibregel definiert. Diese Auflistung verfügt über ein Attribut namens LogicalGrouping , das steuert, wie Bedingungen ausgewertet werden. Wenn eine Regel Bedingungen aufweist, wird die Regelaktion nur ausgeführt, wenn das Regelmuster übereinstimmen und:

  • Alle Bedingungen wurden als "true" ausgewertet, vorausgesetzt, dass logicalGrouping="MatchAll" verwendet wurde.
  • Mindestens eine der Bedingungen wurde als wahr ausgewertet, vorausgesetzt, dass logicalGrouping="MatchAny" verwendet wurde.

Eine Bedingung wird durch Angeben der folgenden Eigenschaften definiert:

  • Eingabezeichenfolge
  • Typ der Übereinstimmung

Bedingungseingabe gibt an, welches Element als Eingabe für die Bedingungsauswertung verwendet werden soll. Bedingungseingabe ist eine beliebige Zeichenfolge, die Servervariablen und Back-References auf vorherige Bedingungsmuster und/oder Regelmuster enthalten kann.

Der Übereinstimmungstyp kann eine der folgenden drei Optionen sein:

  • IsFile – Dieser Übereinstimmungstyp wird verwendet, um zu bestimmen, ob die Eingabezeichenfolge einen physischen Pfad zu einer Datei in einem Dateisystem enthält. Wenn keine Bedingungseingabezeichenfolge angegeben ist, verwendet das URL Rewrite Module den physischen Pfad der angeforderten Datei als Standardwert für die Bedingungseingabe. Dieser Übereinstimmungstyp kann nur für verteilte Regeln verwendet werden.

  • IsDirectory – Dieser Übereinstimmungstyp wird verwendet, um zu bestimmen, ob die Eingabezeichenfolge einen physischen Pfad zu einem Verzeichnis in einem Dateisystem enthält. Wenn keine Bedingungseingabezeichenfolge angegeben ist, verwendet das URL Rewrite Module den physischen Pfad der angeforderten Datei als Standardwert für die Bedingungseingabe. Dieser Übereinstimmungstyp kann nur für verteilte Regeln verwendet werden.

  • Muster – Dieser Übereinstimmungstyp wird verwendet, um eine Bedingung auszudrücken, bei der eine beliebige Eingabezeichenfolge mit einem regulären Ausdrucksmuster abgeglichen wird. Ein Bedingungsmuster kann entweder mithilfe der Syntax regulärer Ausdrücke oder mithilfe einer Wild Karte syntax angegeben werden. Der Typ des musters, das in einer Bedingung verwendet werden soll, hängt vom Wert des musterSyntax-Flags ab , das für die Regel definiert ist, zu der diese Bedingung gehört. Dieser Bedingungstyp weist zwei verwandte Attribute auf, die den Musterabgleich steuern:

    • pattern – Verwenden Sie dieses Attribut, um das tatsächliche Muster anzugeben.
    • ignoreCase – Verwenden Sie dieses Attribut, um zu steuern, ob der Musterabgleich für die Bedingung die Groß-/Kleinschreibung beachtet oder die Groß-/Kleinschreibung nicht beachtet werden soll.

Darüber hinaus kann das Ergebnis der Bedingungsauswertung mithilfe des Negate-Attributs negiert werden. Dies kann verwendet werden, um eine Bedingung anzugeben, die überprüft, ob die angeforderte URL KEINE Datei ist, wie im folgenden Beispiel gezeigt:

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

Regelaktion

Eine Neuschreibregelaktion wird ausgeführt, wenn die aktuelle URL mit dem Regelmuster übereinstimmt und die Bedingungsauswertung erfolgreich war (abhängig von der Regelkonfiguration, entweder alle Bedingungen, die übereinstimmen, oder eine oder mehrere der bedingungen übereinstimmen). Es sind mehrere Arten von Aktionen verfügbar, und das Typ-Attribut des <Aktionskonfigurationselements> kann verwendet werden, um anzugeben, welche Aktion die Regel ausführt. In den folgenden Abschnitten werden verschiedene Aktionstypen und die Konfigurationsoptionen für bestimmte Aktionstypen beschrieben.

Aktion neu schreiben

Eine Rewrite-Aktion ersetzt die aktuelle URL-Zeichenfolge durch eine Ersetzungszeichenfolge. Eine Ersetzungszeichenfolge muss immer den URL-Pfad angeben (z. B. "contoso/test/default.aspx"). Beachten Sie, dass Ersetzungen, die einen physischen Pfad in einem Dateisystem enthalten (z. B C:\inetpub\wwwroot. ) in IIS nicht unterstützt werden.

Eine Rewrite-Aktion verfügt über die folgenden Konfigurationsoptionen:

  • url – Dies ist die ersetzungszeichenfolge, die beim Umschreiben der aktuellen URL verwendet werden soll. Die Ersetzungs-URL ist ein Zeichenfolgenwert, der Folgendes enthalten kann:

    • Zurückverweise auf die Bedingungs- und Regelmuster. (Weitere Informationen finden Sie im Abschnitt zur Verwendung von Back-References.)
    • Die Servervariablen. (Weitere Informationen finden Sie im Abschnitt zur Verwendung von Servervariablen.)

  • appendQueryString – Gibt an, ob die Abfragezeichenfolge aus der aktuellen URL während der Ersetzung beibehalten wird. Wenn der Wert des AppendQueryString-Flags nicht angegeben ist, wird standardmäßig als WAHR angenommen. Dies bedeutet, dass die Abfragezeichenfolge aus der ursprünglichen URL an die ersetzte URL angefügt wird.

Umleitungsaktion

Eine Umleitungsaktion weist das URL-Modul neu zu schreiben, um eine Umleitungsantwort an den Client zurückzusenden. Der Umleitungsstatuscode (3xx) kann als Parameter für diese Aktion angegeben werden. Das Feld "Ort" der Antwort enthält die in der Regel angegebene Ersetzungszeichenfolge.

Die Ersetzungs-URL für die Umleitungsregel kann in einem der folgenden Formulare angegeben werden:

  • Relativer URL-Pfad – contoso/test/default.aspx
  • Absoluter URI – https://example.com/contoso/test/default.aspx

Die Verwendung einer Umleitungsaktion bedeutet, dass nach der Umleitung keine nachfolgenden Regeln für die aktuelle URL ausgewertet werden.

Eine Umleitungsaktion verfügt über die folgenden Konfigurationsoptionen:

  • url – Verwendet eine Ersetzungszeichenfolge als Umleitungs-URL. Eine Ersetzungs-URL ist eine Zeichenfolge, die Folgendes enthalten kann:

    • Zurückverweise auf die Bedingungs- und Regelmuster. (Weitere Informationen finden Sie im Abschnitt zur Verwendung von Back-References.)
    • Die Servervariablen. (Weitere Informationen finden Sie im Abschnitt zur Verwendung von Servervariablen.)

  • appendQueryString – Gibt an, ob die Abfragezeichenfolge aus der aktuellen URL während der Ersetzung beibehalten werden soll. Wenn das AppendQueryString-Flag nicht angegeben ist, wird standardmäßig als WAHR angenommen. Dies bedeutet, dass die Abfragezeichenfolge aus der ursprünglichen URL an die ersetzte URL angefügt wird.

  • redirectType – Gibt den Statuscode an, der während der Umleitung verwendet werden soll:

    • 301 – Permanent
    • 302 – Gefunden
    • 303 – Siehe weitere
    • 307 – Vorübergehend

CustomResponse-Aktion

Eine CustomResponse-Aktion bewirkt, dass das URL Rewrite Module mithilfe eines vom Benutzer angegebenen Statuscodes, Untercode und Grund auf den HTTP-Client reagiert. Die Verwendung einer CustomResponse-Aktion bedeutet, dass nach ausführung dieser Aktion keine nachfolgenden Regeln für die aktuelle URL ausgewertet werden.

Die Aktion "CustomResponse" verfügt über die folgenden Konfigurationsoptionen:

  • statusCode– Gibt den Statuscode an, der als Reaktion auf den Client verwendet werden soll.
  • subStatusCode – Gibt den unterstatus-Code an, der als Reaktion auf den Client verwendet werden soll.
  • statusReason – Gibt den Grund für die Verwendung mit dem Statuscode an.
  • statusDescription – Gibt die eine Zeilenbeschreibung an, die im Textkörper der Antwort eingefügt werden soll.

AbortRequest-Aktion

Eine AbortRequest-Aktion bewirkt, dass das URL Rewrite Module die HTTP-Verbindung für die aktuelle Anforderung abbricht. Die Aktion weist keine Parameter auf. Die Verwendung dieser Aktion bedeutet, dass nach ausführung dieser Aktion keine nachfolgenden Regeln für die aktuelle URL ausgewertet werden.

Keine Aktion

Eine None-Aktion wird verwendet, um anzugeben, dass keine Aktion ausgeführt wird.

Verwenden von Servervariablen in Neuschreibregeln

Servervariablen stellen zusätzliche Informationen zu aktuellen HTTP-Anforderungen bereit. Sie können diese Informationen verwenden, um Entscheidungen neu zu schreiben oder die umgeschriebene URL zu verfassen. Servervariablen können an den folgenden Speicherorten innerhalb von Umschreibregeln referenziert werden:

  • In der Bedingungseingabezeichenfolge

  • In Regelersetzungszeichenfolgen, insbesondere:

    • URL-Attribut der Aktion "Neu schreiben" und "Umleitung"
    • statusLine und responseLine einer CustomResponse-Aktion

Servervariablen können mithilfe der {VARIABLE_NAME}-Syntax referenziert werden. Die folgende Bedingung verwendet z. B. die servervariable QUERY_STRING:

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

Servervariablen können auch für den Zugriff auf HTTP-Header aus der aktuellen Anforderung verwendet werden. Jeder von der aktuellen Anforderung bereitgestellte HTTP-Header wird als Servervariable dargestellt, deren Name gemäß dieser Benennungskonvention generiert wird:

  1. Alle Strichsymbole ("-") im HTTP-Headernamen werden in Unterstrichsymbole ("_") konvertiert.
  2. Alle Buchstaben im HTTP-Headernamen werden in Großbuchstaben konvertiert.
  3. Das Präfix "HTTP_" wird dem Kopfzeilennamen hinzugefügt.

Um beispielsweise über eine Umschreibregel auf den HTTP-Header "User-Agent" zuzugreifen, können Sie die Servervariable {HTTP_USER_AGENT} verwenden.

Verwenden von Rückverweisen in Neuschreibregeln

Teile von Regeln oder Bedingungeneingaben können in Backverweise erfasst werden. Diese können dann zum Erstellen von Ersetzungs-URLs innerhalb von Regelaktionen oder zum Erstellen von Eingabezeichenfolgen für Regelbedingungen verwendet werden.

Back-References werden auf unterschiedliche Weise generiert, je nachdem, welche Art von Mustersyntax für die Regel verwendet wird. Wenn eine ECMAScript-Mustersyntax verwendet wird, kann ein Rückverweis erstellt werden, indem Klammern um den Teil des Musters platziert werden, der den Backverweis erfassen muss. Beispielsweise erfasst das Muster ([0-9]+)/([a-z]+).html 07 und Artikel in Back-References aus dieser angeforderten URL: 07/article.html. Wenn die Mustersyntax "Wild Karte" verwendet wird, werden die Rückverweise immer erstellt, wenn ein Sternchen (*) im Muster verwendet wird. Es werden keine Rückverweise erstellt, wenn "?" im Muster verwendet wird. Beispielsweise erfasst das Muster */*.html contoso und testt in Back-References von dieser angeforderten URL: contoso/test.html.

Die Verwendung von Rückbezügen ist unabhängig davon, welche Mustersyntax zum Erfassen verwendet wurde, identisch. Back-References können an den folgenden Speicherorten innerhalb von Rewrite-Regeln verwendet werden:

  • In Bedingungseingabezeichenfolgen

  • In Regelaktionen, insbesondere:

    • URL-Attribut der Aktion "Neu schreiben" und "Umleitung"
    • statusLine und responseLine einer CustomResponse-Aktion

  • In einem Schlüsselparameter zur Neuschreibung der Zuordnung

Rückverweise auf Bedingungsmuster werden durch {C:N} identifiziert, wobei N zwischen 0 und 9 liegt. Back-References to rule patterns are identified by {R:N} where N is from 0 to 9. Beachten Sie, dass für beide Typen von Back-References{ R:0} und {C:0} die übereinstimmende Zeichenfolge enthalten wird.

Beispiel:

^(www\.)(.*)$

Für die Zeichenfolge: www.foo.com Die Rückverweise werden wie folgt indiziert:

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

Innerhalb einer Regelaktion können Sie die Rückverweise auf das Regelmuster und die letzte übereinstimmende Bedingung dieser Regel verwenden. In einer Bedingungseingabezeichenfolge können Sie die Rückverweise auf das Regelmuster und auf die zuvor übereinstimmende Bedingung verwenden.

Im folgenden Regelbeispiel wird veranschaulicht, wie Backverweise erstellt und referenziert werden:

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

Interaktion mit IIS-Ausgabezwischenspeicherung

Das URL Rewrite Module steuert das IIS-Ausgabecacheverhalten, um:

  1. Nutzen Sie optimal den Kernelmodus und die Ausgabezwischenspeicherung von Antworten für umgeschriebene URLs, wodurch die Leistung der Webanwendung verbessert wird, die das URL Rewrite Module verwendet.
  2. Verhindern Sie das Zwischenspeichern von Antworten, wenn die Zwischenspeicherungslogik aufgrund von URL-Umschreibungen verletzt werden kann.

Das Modul steuert die Ausgabezwischenspeicherung, indem entweder bestimmte Zwischenspeicherungseigenschaften geändert oder die Zwischenspeicherung vollständig deaktiviert wird. Das Modul kann die Ausgabezwischenspeicherung nicht aktivieren, wenn es von der IIS-Konfiguration oder von einem anderen Modul in der IIS-Pipeline deaktiviert wurde. Die Ausgabezwischenspeicherung wird wie folgt gesteuert:

  1. Das Modul legt immer die Cacheeinstellung für den Benutzermodus fest:ByHeader="HTTP_X_ORIGINAL_URL". Dadurch wird sichergestellt, dass beim Aktivieren des Zwischenspeicherns im Benutzermodus die ursprüngliche URL berücksichtigt wird, um einen Schlüssel für den Cacheeintrag zu erstellen.

  2. Wenn ein Umschreibregelsatz Servervariablen mit Werten verwendet, die entweder während der gesamten Lebensdauer des Prozesses konstant sind oder von der angeforderten URL abgeleitet werden, gilt der Regelsatz als sicher für die Ausgabezwischenspeicherung. Dies bedeutet, dass das URL-Rewrite-Modul keine vorhandene Zwischenspeicherungsrichtlinie auf andere Weise ändert als das Festlegen von "VaryByHeader ", wie in Schritt 1 beschrieben.

    Die folgenden Servervariablen, wenn sie in Neuschreibregeln verwendet werden, wirken sich nicht auf die Ausgabezwischenspeicherungsrichtlinie aus:

    • "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. Wenn ein Umschreibregelsatz eine Servervariable verwendet, die nicht in der obigen Liste Erwähnung wird, wird der Regelsatz für die Ausgabezwischenspeicherung als unsicher angesehen. Dies bedeutet, dass das URL Rewrite Module das Zwischenspeichern des Kernelmodus für alle Anforderungen deaktiviert, unabhängig davon, ob die Anforderungs-URLs umgeschrieben wurden oder nicht. Darüber hinaus ändert das Modul die Zwischenspeicherungsrichtlinie für den Cache im Benutzermodus, indem die Cacheeigenschaft "VaryByValue " festgelegt wird, um die verkettete Zeichenfolge aller Servervariablenwerte zu enthalten, die im Regelsatz verwendet werden.

Zeichenfolgenfunktionen

Es stehen drei Zeichenfolgenfunktionen zum Ändern der Werte innerhalb einer Umschreibregelaktion sowie für alle Bedingungen zur Verfügung:

  • ToLower : Gibt die in Kleinbuchstaben konvertierte Eingabezeichenfolge zurück.
  • UrlEncode : Gibt die Eingabezeichenfolge zurück, die in das URL-codierte Format konvertiert wurde. Diese Funktion kann verwendet werden, wenn die Ersetzungs-URL in der Umschreibregel Sonderzeichen enthält (z. B. nicht-ASCII- oder URI-unsichere Zeichen).
  • UrlDecode : Decodiert die URL-codierte Eingabezeichenfolge. Diese Funktion kann verwendet werden, um eine Bedingungseingabe zu decodieren, bevor sie mit einem Muster übereinstimmen.

Die Funktionen können mithilfe der folgenden Syntax aufgerufen werden:

{function_name:any_string}

Wo "function_name" in eof the following sein kann: "ToLower", "UrlEncode", "UrlDecode". "Any_string" kann entweder eine Literalzeichenfolge oder eine Zeichenfolge sein, die mithilfe von Servervariablen oder Backverweise erstellt wurde. Beispielsweise sind die folgenden gültigen Aufrufe von Zeichenfolgenfunktionen:

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

Die Zeichenfolgenfunktionen können an den folgenden Stellen innerhalb von Rewrite-Regeln verwendet werden:The string functions can be used in the following locations within rewrite rules:

  • In Bedingungseingabezeichenfolgen

  • In Regelersetzungszeichenfolgen, insbesondere:

    • URL-Attribut von Rewrite- und Umleitungsaktionen
    • statusLine- und responseLine-Attribute einer CustomResponse-Aktion

Ein Beispiel für eine Regel, die die ToLower-Funktion verwendet:

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

Ein Beispiel für eine Regel, die die UrlEncode-Funktion verwendet:

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

Ein Beispiel für eine Regel, die die UrlDecode-Funktion verwendet:

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

Umschreibungszuordnungen

Eine Umschreibungszuordnung ist eine beliebige Sammlung von Namens-Wert-Paaren, die innerhalb von Umschreibregeln verwendet werden können, um die Ersetzungs-URL während der Neuschreibung zu generieren. Rewrite-Zuordnungen sind hilfreich, wenn Sie sehr viele Rewrite-Regeln haben, die alle statische Zeichenfolgen verwenden (also wenn kein Musterabgleich verwendet wird). In diesen Fällen können Sie anstelle eines großen Satzes einfacher Neuschreibregeln alle Zuordnungen als Schlüssel und Werte zwischen der Eingabe-URL und der Ersetzungs-URL in die Neuschreibungszuordnung einfügen. Um dann die Ersetzungs-URL basierend auf der Eingabe-URL nachzuschlagen, verfügen Sie über eine Neuschreibregel, die auf die Neuschreibzuordnung verweist.

Eine umschreibende Zuordnung definiert eine benannte Auflistung von Namens-Wert-Paarzeichenfolgen, wie im folgenden Beispiel gezeigt:

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

Eine Umschreibungszuordnung wird eindeutig durch ihren Namen identifiziert und kann Null- oder mehr Schlüsselwerteinträge enthalten. Darüber hinaus kann eine Umschreibungszuordnung den Standardwert angeben, der verwendet werden soll, wenn ein Schlüssel nicht gefunden wird. Dies wird mithilfe des defaultValue-Attributs gesteuert. Standardmäßig wird eine leere Zeichenfolge als Standardwert verwendet.

Es kann eine beliebige Anzahl von Neuschreibzuordnungen auf einer beliebigen Konfigurationsebene vorhanden sein, mit Ausnahme der Dateiebene. Umschreiben von Zuordnungen befindet sich innerhalb des <Rewrite Karten-Auflistungselements>.

Auf neu geschriebene Zuordnungen wird in einer Umschreibregel mithilfe der folgenden Syntax verwiesen:

{RewriteMapName:Key}

Dabei kann der Key-Parameter eine beliebige Zeichenfolge sein und Back-References auf Regel- oder Bedingungsmuster enthalten. Beispielsweise sind die folgenden gültigen Verwendungen einer Umschreibungszuordnung zulässig:

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

Ein Verweis auf eine Neuschreibzuordnung wird durch den Wert ersetzt, der mithilfe des Schlüssels gesucht wurde, der als Parameter in einem Umschreibzuordnungsverweis übergeben wurde. Wenn kein Schlüssel gefunden wurde, wird der Standardwert für diese Umschreibungszuordnung verwendet.

Auf eine Neuschreibzuordnung kann an den folgenden Stellen innerhalb von Umschreibregeln verwiesen werden:

  • In Bedingungseingabezeichenfolge

  • In Regelersetzungszeichenfolgen, insbesondere:

    • URL-Attribut von Rewrite- und Umleitungsaktionen
    • statusLine und responseLine von CustomResponse-Aktionen

Beispiel 1: Mit einer wie folgt definierten Umschreibungszuordnung:

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

Und eine wie folgt definierte Neuschreibregel:

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

Die angeforderte URL /diagnostic wird als /default.aspx?tabid=2&subtabid=29 umgeschrieben.
Die angeforderte URL /webcasts wird in /default.aspx?tabid=2&subtabid=24 umgeschrieben.
Die angeforderte URL /php wird in /default.aspx?tabid=7116 umgeschrieben.
Die angeforderte URL /default.aspx wird nicht neu geschrieben, da die Neuschreibungszuordnung kein Element mit key="/default.aspx" enthält. Daher gibt die Neuschreibungszuordnung eine leere Zeichenfolge zurück, die nicht mit dem Bedingungsmuster übereinstimmt, daher wird die Regelaktion nicht ausgeführt.

Beispiel 2: Mit einer wie folgt definierten Umschreibungszuordnung:

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

Und eine wie folgt definierte Neuschreibregel:

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

Die angeforderte URL /default.aspx?tabid=2&subtabid=29 wird umgeleitet.http://www.contoso.com/diagnostics
Die angeforderte URL /default.aspx?tabid=2&subtabid=24 wird umgeleitet.http://www.contoso.com/webcasts
Die angeforderte URL /default.aspx?tabid=7116 wird umgeleitet.http://www.contoso.com/php
Die angeforderte URL /default.aspx wird nicht umgeleitet, da die Umschreibungszuordnung kein Element mit key="/default.aspx" enthält. Daher gibt die Umschreibungszuordnung eine leere Zeichenfolge zurück, die nicht mit dem Bedingungsmuster übereinstimmt, daher wird keine Regelaktion ausgeführt.