Bagikan melalui

Referensi Konfigurasi Modul Penulisan Ulang URL

  • Artikel

oleh Ruslan Yakushev

Artikel ini memberikan gambaran umum tentang Modul Penulisan Ulang URL dan menjelaskan konsep konfigurasi yang digunakan oleh modul.

Gambaran Umum Fungsionalitas

Url Rewrite Module menulis ulang URL permintaan ke alamat sederhana, mudah digunakan, dan mudah dicari yang ditampilkan kepada pengguna atau di aplikasi Web. Penulisan Ulang URL menggunakan aturan yang ditentukan untuk mengevaluasi lalu memetakan URL permintaan ke alamat yang ditentukan dalam aturan sebelum diproses oleh server Web IIS. Anda dapat menentukan logika penulisan ulang URL yang menyertakan ekspresi reguler dan kartubebas, dan aturan dapat diterapkan berdasarkan URL permintaan, header HTTP, dan variabel server. Meskipun tujuan utama modul adalah untuk menulis ulang URL permintaan ke URL yang lebih ramah, Anda juga dapat menggunakan modul untuk menentukan aturan yang melakukan pengalihan, mengirim respons kustom, atau membatalkan permintaan.

Gambaran Umum Aturan Penulisan Ulang

Aturan penulisan ulang menentukan logika tentang apa yang harus dibandingkan atau cocok dengan URL permintaan, dan apa yang harus dilakukan jika perbandingan berhasil.

Aturan penulisan ulang terdiri dari bagian-bagian berikut:

  • Pola – Pola aturan digunakan untuk menentukan ekspresi reguler atau pola kartubebas yang digunakan untuk mencocokkan string URL.
  • Kondisi – Kumpulan kondisi opsional digunakan untuk menentukan operasi logis tambahan yang akan dilakukan jika string URL cocok dengan pola aturan. Dalam kondisi, Anda dapat memeriksa nilai header HTTP atau variabel server tertentu, atau memverifikasi apakah URL yang diminta sesuai dengan file atau direktori pada sistem file fisik.
  • Tindakan – Tindakan digunakan untuk menentukan apa yang harus dilakukan jika string URL cocok dengan pola aturan dan semua kondisi aturan terpenuhi.

Cakupan Aturan Penulisan Ulang

Aturan penulisan ulang dapat didefinisikan dalam dua koleksi yang berbeda:

  • <globalRules> – Aturan dalam koleksi ini hanya dapat ditentukan pada tingkat server. Aturan global digunakan untuk menentukan logika penulisan ulang URL di seluruh server. Aturan ini didefinisikan dalam file ApplicationHost.config, dan tidak dapat ditimpa atau dinonaktifkan pada tingkat konfigurasi yang lebih rendah. Aturan global selalu beroperasi pada jalur URL absolut (yaitu, URI yang diminta tanpa nama server). Aturan ini dievaluasi lebih awal dalam alur pemrosesan permintaan IIS (peristiwa PreBeginRequest ).
  • <rules> – Aturan dalam koleksi ini disebut aturan terdistribusi, dan dapat ditentukan pada tingkat apa pun dalam hierarki konfigurasi. Aturan terdistribusi digunakan untuk menentukan logika penulisan ulang URL khusus untuk cakupan konfigurasi tertentu. Jenis aturan ini dapat ditambahkan pada tingkat konfigurasi apa pun dengan menggunakan file Web.config atau dengan menggunakan <location> tag dalam file ApplicationHost.config atau Web.config. Aturan terdistribusi beroperasi pada jalur URL, relatif terhadap lokasi file Web.config tempat aturan tersebut ditentukan. Dalam kasus di mana aturan terdistribusi ditentukan di dalam <location> tag, aturan tersebut beroperasi pada jalur URL, relatif terhadap jalur yang <location> ditentukan untuk tag tersebut. Aturan ini dievaluasi pada peristiwa BeginRequest di alur IIS.

Evaluasi Aturan

Setiap tingkat konfigurasi di IIS dapat memiliki nol atau lebih aturan penulisan ulang yang ditentukan. Aturan dievaluasi dalam urutan yang sama di mana aturan ditentukan. Modul Penulisan Ulang URL memproses sekumpulan aturan dengan menggunakan algoritma berikut:

  1. Pertama, URL dicocokkan dengan pola aturan. Jika tidak cocok, Modul Penulisan Ulang URL segera berhenti memproses aturan tersebut, dan melanjutkan ke aturan berikutnya.
  2. Jika pola cocok dan tidak ada kondisi untuk aturan, Modul Penulisan Ulang URL melakukan tindakan yang ditentukan untuk aturan ini dan kemudian melanjutkan ke aturan berikutnya, di mana ia menggunakan URL pengganti sebagai input untuk aturan tersebut.
  3. Jika pola cocok dan ada kondisi untuk aturan, Modul Penulisan Ulang URL mengevaluasi kondisi. Jika evaluasi berhasil, tindakan aturan yang ditentukan dilakukan, lalu URL yang ditulis ulang digunakan sebagai input ke aturan berikutnya

Aturan mungkin mengaktifkan bendera StopProcessing . Ketika tindakan aturan dilakukan (yaitu aturan yang cocok) dan bendera ini diaktifkan, itu berarti bahwa tidak ada lagi aturan berikutnya yang akan diproses dan permintaan akan diteruskan ke alur permintaan IIS. Secara default, bendera ini dinonaktifkan.

Pewarisan Aturan

Jika aturan ditentukan pada beberapa tingkat konfigurasi, Modul Penulisan Ulang URL mengevaluasi aturan dalam urutan berikut:

  1. Mengevaluasi semua aturan global.
  2. Evaluasi seperangkat aturan yang menyertakan aturan terdistribusi dari tingkat konfigurasi induk serta aturan dari tingkat konfigurasi saat ini. Evaluasi dilakukan dalam urutan induk ke anak, yang berarti bahwa aturan induk dievaluasi terlebih dahulu dan aturan yang ditentukan pada tingkat anak terakhir dievaluasi terakhir.

Mempertahankan URL Asli

Modul Penulisan Ulang URL mempertahankan jalur URL asli yang diminta dalam variabel server berikut:

  • HTTP_X_ORIGINAL_URL – variabel server ini berisi URL asli dalam format yang didekodekan;
  • UNENCODED_URL – variabel server ini berisi URL asli persis seperti yang diminta oleh klien Web, dengan semua pengodean asli dipertahankan.

Mengakses Bagian URL dari Aturan Penulisan Ulang

Penting untuk memahami bagaimana bagian tertentu dari string URL dapat diakses dari aturan penulisan ulang.

Untuk URL HTTP dalam formulir ini: http(s)://<host>:<port>/<path>?<querystring>

  • Jalur <> dicocokkan dengan pola aturan.
  • Querystring <> tersedia dalam variabel server yang disebut QUERY_STRING dan dapat diakses dengan menggunakan kondisi dalam aturan.
  • Host <> tersedia dalam variabel server HTTP_HOST dan dapat diakses dengan menggunakan kondisi dalam aturan.
  • <Port> tersedia dalam variabel server SERVER_PORT dan dapat diakses dengan menggunakan kondisi dalam aturan.
  • Variabel server SERVER_PORT_SECURE dan HTTPS dapat digunakan untuk menentukan apakah koneksi aman digunakan. Variabel server ini dapat diakses dengan menggunakan kondisi dalam aturan.
  • Variabel server REQUEST_URI dapat digunakan untuk mengakses seluruh jalur URL yang diminta, termasuk string kueri.

Misalnya, jika permintaan dibuat untuk URL ini: http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3, dan aturan penulisan ulang ditentukan pada tingkat situs, maka:

  • Pola aturan mendapatkan string content/default.aspx URL sebagai input.
  • Variabel server QUERY_STRING berisi tabid=2&subtabid=3.
  • Variabel server HTTP_HOST berisi www.mysite.com.
  • Variabel server SERVER_PORT berisi 80.
  • Variabel server SERVER_PORT_SECURE berisi 0 dan HTTPS berisi OFF.
  • Variabel server REQUEST_URI berisi /content/default.aspx?tabid=2&subtabid=3.
  • Variabel server PATH_INFO berisi /content/default.aspx.

Perhatikan bahwa string URL input yang diteruskan ke aturan terdistribusi selalu relatif terhadap lokasi file Web.config tempat aturan ditentukan. Misalnya, jika permintaan dibuat untuk http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3, dan aturan penulisan ulang ditentukan dalam direktori /content , maka aturan mendapatkan string URL ini default.aspx sebagai input.

Konfigurasi Aturan Penulisan Ulang

Pola Aturan

Pola aturan penulisan ulang digunakan untuk menentukan pola yang dibandingkan dengan jalur URL saat ini. Saat ini, dalam konteks ini, berarti nilai jalur URL saat aturan diterapkan. Jika ada aturan yang mendahului aturan saat ini, aturan tersebut mungkin telah cocok dengan URL asli yang diminta dan memodifikasinya. String URL yang dievaluasi terhadap pola tidak menyertakan string kueri. Untuk menyertakan string kueri dalam evaluasi aturan, Anda dapat menggunakan variabel server QUERY_STRING dalam kondisi aturan. Untuk informasi selengkapnya, lihat "Menggunakan variabel server dalam aturan penulisan ulang".

Pola ditentukan dalam elemen kecocokan <> dari aturan penulisan ulang.

Sintaks pola aturan

Sintaks pola aturan dapat ditentukan dengan menggunakan atribut patternSyntax aturan. Atribut ini dapat diatur ke salah satu opsi berikut:

ECMAScript – Sintaks ekspresi reguler yang kompatibel dengan Perl (sesuai standar ECMAScript). Ini adalah opsi default untuk aturan apa pun. Ini adalah contoh format pola: "^([_0-9a-zA-Z-]+/)? (wp-.*)"

Wildcard – Sintaks wildcard yang digunakan dalam modul pengalihan HTTP IIS. Berikut ini adalah contoh pola dalam format ini: "/Scripts/*_in.???", di mana tanda bintang ("*") berarti "cocokkan sejumlah karakter apa pun dan ambil dalam referensi belakang" dan "?" berarti cocok persis dengan satu karakter (tidak ada referensi belakang yang dibuat).

Cakupan atribut patternSyntax adalah per aturan, yang berarti bahwa itu berlaku untuk pola aturan saat ini dan untuk semua pola yang digunakan dalam kondisi aturan tersebut.

Properti pola aturan

Pola dapat dinegasikan dengan menggunakan atribut meniadakan elemen kecocokan<>. Ketika atribut ini digunakan, tindakan aturan dilakukan hanya jika URL saat ini tidak cocok dengan pola yang ditentukan.

Secara default, pencocokan pola tidak sensitif huruf besar/kecil digunakan. Untuk mengaktifkan sensitivitas kasus, Anda dapat menggunakan atribut ignoreCase dari elemen pencocokan <> aturan.

Kondisi aturan

Kondisi aturan memungkinkan penentuan logika tambahan untuk evaluasi aturan, yang dapat didasarkan pada input selain hanya string URL saat ini. Aturan apa pun dapat memiliki nol atau lebih kondisi. Kondisi aturan dievaluasi setelah kecocokan pola aturan berhasil.

Kondisi didefinisikan dalam <kumpulan kondisi> aturan penulisan ulang. Koleksi ini memiliki atribut yang disebut logicalGrouping yang mengontrol bagaimana kondisi dievaluasi. Jika aturan memiliki kondisi, tindakan aturan dilakukan hanya jika pola aturan cocok dan:

  • Semua kondisi dievaluasi sebagai benar, asalkan logicalGrouping="MatchAll" digunakan.
  • Setidaknya salah satu kondisi dievaluasi sebagai benar, asalkan logicalGrouping="MatchAny" digunakan.

Kondisi ditentukan dengan menentukan properti berikut:

  • Input string
  • Jenis pencocokan

Input kondisi menentukan item mana yang akan digunakan sebagai input untuk evaluasi kondisi. Input kondisi adalah string arbitrer yang dapat mencakup variabel server dan referensi balik ke pola kondisi sebelumnya dan/atau pola aturan.

Jenis kecocokan bisa menjadi salah satu dari tiga opsi berikut:

  • IsFile – Jenis kecocokan ini digunakan untuk menentukan apakah string input berisi jalur fisik ke file pada sistem file. Jika string input kondisi tidak ditentukan, Modul Penulisan Ulang URL menggunakan jalur fisik file yang diminta sebagai nilai default untuk input kondisi. Jenis kecocokan ini hanya dapat digunakan untuk aturan terdistribusi.

  • IsDirectory – Jenis kecocokan ini digunakan untuk menentukan apakah string input berisi jalur fisik ke direktori pada sistem file. Jika string input kondisi tidak ditentukan, Modul Penulisan Ulang URL menggunakan jalur fisik file yang diminta sebagai nilai default untuk input kondisi. Jenis kecocokan ini hanya dapat digunakan untuk aturan terdistribusi.

  • Pola – Jenis kecocokan ini digunakan untuk mengekspresikan kondisi di mana string input arbitrer dicocokkan dengan pola ekspresi reguler. Pola kondisi dapat ditentukan dengan menggunakan sintaks ekspresi reguler atau dengan menggunakan sintaks kartubebas. Jenis pola yang digunakan dalam kondisi tergantung pada nilai bendera patternSyntax yang ditentukan untuk aturan tempat kondisi ini berada. Jenis kondisi ini memiliki dua atribut terkait yang mengontrol pencocokan pola:

    • pattern – Gunakan atribut ini untuk menentukan pola aktual.
    • ignoreCase – Gunakan atribut ini untuk mengontrol apakah pencocokan pola untuk kondisi harus peka huruf besar/kecil atau tidak peka huruf besar/kecil.

Selain itu, hasil evaluasi kondisi dapat dinegasikan dengan menggunakan atribut negate . Ini dapat digunakan untuk menentukan kondisi yang memeriksa apakah URL yang diminta BUKAN file, seperti dalam contoh berikut:

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

Tindakan aturan

Tindakan aturan penulisan ulang dilakukan ketika URL saat ini cocok dengan pola aturan dan evaluasi kondisi berhasil (tergantung pada konfigurasi aturan, baik semua kondisi yang cocok atau satu atau beberapa kondisi yang cocok). Ada beberapa jenis tindakan yang tersedia, dan atribut <jenis elemen konfigurasi tindakan> dapat digunakan untuk menentukan tindakan mana yang dilakukan aturan. Bagian berikut menjelaskan berbagai jenis tindakan dan opsi konfigurasi yang terkait dengan jenis tindakan tertentu.

Tindakan penulisan ulang

Tindakan Penulisan Ulang menggantikan string URL saat ini dengan string pengganti. String pengganti harus selalu menentukan jalur URL (misalnya, contoso/test/default.aspx). Perhatikan bahwa substitusi yang berisi jalur fisik pada sistem file (misalnya, C:\inetpub\wwwroot) tidak didukung di IIS.

Tindakan Penulisan Ulang memiliki opsi konfigurasi berikut:

  • url – Ini adalah string pengganti yang akan digunakan saat menulis ulang URL saat ini. URL pengganti adalah nilai string yang dapat menyertakan yang berikut ini:

    • Referensi kembali ke kondisi dan pola aturan. (Untuk informasi selengkapnya, lihat bagian tentang cara menggunakan referensi balik.)
    • Variabel server. (Untuk informasi selengkapnya, lihat bagian tentang cara menggunakan variabel server.)

  • appendQueryString – Menentukan apakah string kueri dari URL saat ini dipertahankan selama penggantian. Secara default, jika nilai bendera appendQueryString tidak ditentukan, nilai tersebut diasumsikan TRUE. Ini berarti bahwa string kueri dari URL asli ditambahkan ke URL yang diganti.

Tindakan pengalihan

Tindakan Pengalihan menginstruksikan Modul Penulisan Ulang URL untuk mengirim respons pengalihan kembali ke klien. Kode status pengalihan (3xx) dapat ditentukan sebagai parameter untuk tindakan ini. Bidang Lokasi respons berisi string substitusi yang ditentukan dalam aturan.

URL pengganti untuk aturan pengalihan dapat ditentukan dalam salah satu formulir berikut:

  • Jalur URL Relatif – contoso/test/default.aspx
  • URI absolut – https://example.com/contoso/test/default.aspx

Penggunaan tindakan Pengalihan menyiratkan bahwa tidak ada aturan berikutnya yang dievaluasi untuk URL saat ini setelah pengalihan dilakukan.

Tindakan Pengalihan memiliki opsi konfigurasi berikut:

  • url – Menggunakan string pengganti sebagai URL pengalihan. URL pengganti adalah string yang dapat menyertakan yang berikut ini:

    • Referensi kembali ke kondisi dan pola aturan. (Untuk informasi selengkapnya, lihat bagian tentang cara menggunakan referensi balik.)
    • Variabel server. (Untuk informasi selengkapnya, lihat bagian tentang cara menggunakan variabel server.)

  • appendQueryString – Menentukan apakah string kueri dari URL saat ini harus dipertahankan selama penggantian. Secara default, jika bendera AppendQueryString tidak ditentukan, bendera tersebut diasumsikan TRUE. Ini berarti bahwa string kueri dari URL asli ditambahkan ke URL yang diganti.

  • redirectType – Menentukan kode status yang akan digunakan selama pengalihan:

    • 301 – Permanen
    • 302 – Ditemukan
    • 303 – Lihat lainnya
    • 307 – Sementara

Tindakan Respons Kustom

Tindakan CustomResponse menyebabkan Modul Penulisan Ulang URL merespons klien HTTP dengan menggunakan kode status, subkode, dan alasan yang ditentukan pengguna. Penggunaan tindakan CustomResponse menyiratkan bahwa tidak ada aturan berikutnya yang dievaluasi untuk URL saat ini setelah tindakan ini dilakukan.

Tindakan CustomResponse memiliki opsi konfigurasi berikut:

  • statusCode– Menentukan kode status yang akan digunakan sebagai respons terhadap klien.
  • subStatusCode – Menentukan kode substatus yang akan digunakan sebagai respons terhadap klien.
  • statusReason – Menentukan alasan frasa untuk digunakan dengan kode status.
  • statusDescription – Menentukan deskripsi satu baris untuk dimasukkan ke dalam isi respons.

Tindakan AbortRequest

Tindakan AbortRequest menyebabkan Modul Penulisan Ulang URL menghilangkan koneksi HTTP untuk permintaan saat ini. Tindakan tidak memiliki parameter apa pun. Penggunaan tindakan ini menyiratkan bahwa tidak ada aturan berikutnya yang dievaluasi untuk URL saat ini setelah tindakan ini dilakukan.

Tidak ada tindakan

Tindakan Tidak Ada digunakan untuk menentukan bahwa tidak ada tindakan yang dilakukan.

Menggunakan variabel server dalam aturan penulisan ulang

Variabel server menyediakan informasi tambahan tentang permintaan HTTP saat ini. Anda dapat menggunakan informasi ini untuk membuat keputusan penulisan ulang atau menyusun URL yang ditulis ulang. Variabel server dapat direferensikan di lokasi berikut dalam aturan penulisan ulang:

  • Dalam string input kondisi

  • Dalam string substitusi aturan, khususnya:

    • atribut url tindakan Rewrite dan Pengalihan
    • statusLine dan responseLine dari tindakan CustomResponse

Variabel server dapat dirujuk dengan menggunakan sintaks {VARIABLE_NAME}. Misalnya, kondisi berikut menggunakan variabel server QUERY_STRING:

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

Variabel server juga dapat digunakan untuk mengakses header HTTP dari permintaan saat ini. Header HTTP apa pun yang disediakan oleh permintaan saat ini direpresentasikan sebagai variabel server yang memiliki nama yang dihasilkan sesuai dengan konvensi penamaan ini:

  1. Semua simbol tanda hubung ("-") dalam nama header HTTP dikonversi ke simbol garis bawah ("_").
  2. Semua huruf dalam nama header HTTP dikonversi ke huruf besar/ kecil.
  3. Awalan "HTTP_" ditambahkan ke nama header.

Misalnya, untuk mengakses header HTTP "agen pengguna" dari aturan penulisan ulang, Anda dapat menggunakan variabel server {HTTP_USER_AGENT}.

Menggunakan referensi balik dalam aturan penulisan ulang

Bagian dari aturan atau input kondisi dapat diambil dalam referensi belakang. Ini kemudian dapat digunakan untuk membangun URL substitusi dalam tindakan aturan atau untuk membangun string input untuk kondisi aturan.

Referensi balik dihasilkan dengan cara yang berbeda, tergantung pada jenis sintaks pola mana yang digunakan untuk aturan. Saat sintaks pola ECMAScript digunakan, referensi balik dapat dibuat dengan menempatkan tanda kurung di sekitar bagian pola yang harus mengambil referensi belakang. Misalnya, pola ([0-9]+)/([a-z]+).html akan menangkap 07 dan artikel dalam referensi balik dari URL yang diminta ini: 07/article.html. Ketika sintaks pola "Wildcard" digunakan, referensi belakang selalu dibuat ketika simbol tanda bintang (*) digunakan dalam pola. Tidak ada referensi belakang yang dibuat ketika "?" digunakan dalam pola. Misalnya pola */*.html akan menangkap contoso dan menguji dalam referensi belakang dari URL yang diminta ini: contoso/test.html.

Penggunaan referensi balik sama terlepas dari sintaks pola mana yang digunakan untuk menangkapnya. Referensi balik dapat digunakan di lokasi berikut dalam aturan penulisan ulang:

  • Dalam kondisi string input

  • Dalam tindakan aturan, khususnya:

    • atribut url tindakan Rewrite dan Pengalihan
    • statusLine dan responseLine dari tindakan CustomResponse

  • Dalam parameter kunci ke peta penulisan ulang

Referensi balik ke pola kondisi diidentifikasi oleh {C:N} di mana N adalah dari 0 hingga 9. Referensi balik ke pola aturan diidentifikasi oleh {R:N} di mana N adalah dari 0 hingga 9. Perhatikan bahwa untuk kedua jenis referensi belakang, {R:0} dan {C:0}, akan berisi string yang cocok.

Misalnya, dalam pola ini:

^(www\.)(.*)$

Untuk string: www.foo.com referensi belakang akan diindeks sebagai berikut:

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

Dalam tindakan aturan, Anda dapat menggunakan referensi balik ke pola aturan dan ke kondisi terakhir yang cocok dari aturan tersebut. Dalam string input kondisi, Anda dapat menggunakan referensi balik ke pola aturan dan ke kondisi yang cocok sebelumnya.

Contoh aturan berikut menunjukkan bagaimana referensi balik dibuat dan direferensikan:

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

Interaksi dengan Penembolokan Output IIS

Modul Penulisan Ulang URL mengontrol perilaku cache output IIS untuk:

  1. Secara optimal menggunakan mode kernel dan penembolokan output mode pengguna respons untuk URL yang ditulis ulang, sehingga meningkatkan performa aplikasi Web yang menggunakan Modul Penulisan Ulang URL.
  2. Mencegah penembolokan respons, saat logika penembolokan dapat dilanggar karena penulisan ulang URL.

Modul mengontrol penembolokan output baik dengan mengubah properti penembolokan tertentu atau dengan menonaktifkan penembolokan sama sekali. Modul tidak dapat mengaktifkan penembolokan output jika telah dinonaktifkan oleh konfigurasi IIS atau oleh modul lain dalam alur IIS. Penembolokan output dikontrol sebagai berikut:

  1. Modul selalu mengatur pengaturan cache mode pengguna varyByHeader="HTTP_X_ORIGINAL_URL". Ini memastikan bahwa ketika penembolokan mode pengguna diaktifkan, modul memperhitungkan URL asli untuk membuat kunci untuk entri cache.

  2. Jika seperangkat aturan penulisan ulang menggunakan variabel server dengan nilai yang konstan sepanjang masa proses atau berasal dari URL yang diminta, seperangkat aturan dianggap aman untuk penembolokan output. Ini berarti bahwa Modul Penulisan Ulang URL tidak akan mengubah kebijakan penembolokan yang ada dengan cara apa pun selain mengatur varyByHeader seperti yang dijelaskan di langkah 1.

    Variabel server berikut, ketika digunakan dalam aturan penulisan ulang, tidak menyebabkan efek apa pun pada kebijakan penembolokan 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"
    • "SERVER_SOFTWARE"
    • "SSI_EXEC_DISABLED"

  3. Jika seperangkat aturan penulisan ulang menggunakan variabel server apa pun yang tidak disebutkan dalam daftar di atas, seperangkat aturan dianggap tidak aman untuk penembolokan output. Ini berarti bahwa Modul Penulisan Ulang URL akan menonaktifkan penembolokan mode kernel untuk semua permintaan apakah URL permintaan ditulis ulang atau tidak. Selain itu, modul akan mengubah kebijakan penembolokan untuk cache mode pengguna dengan mengatur properti penembolokan varyByValue untuk berisi string yang digabungkan dari semua nilai variabel server yang digunakan dalam seperangkat aturan.

Fungsi string

Ada tiga fungsi string yang tersedia untuk mengubah nilai dalam tindakan aturan penulisan ulang, serta kondisi apa pun:

  • ToLower - mengembalikan string input yang dikonversi ke huruf kecil.
  • UrlEncode - mengembalikan string input yang dikonversi ke format yang dikodekan URL. Fungsi ini dapat digunakan jika URL pengganti dalam aturan penulisan ulang berisi karakter khusus (misalnya karakter non-ASCII atau URI-tidak aman).
  • UrlDecode - mendekode string input yang dikodekan URL. Fungsi ini dapat digunakan untuk mendekode input kondisi sebelum mencocokkannya dengan pola.

Fungsi dapat dipanggil dengan menggunakan sintaks berikut:

{function_name:any_string}

Di mana "function_name" dapat berada di eof yang berikut: "ToLower", "UrlEncode", "UrlDecode". "Any_string" dapat berupa string harfiah atau string yang dibangun dengan menggunakan variabel server atau referensi belakang. Misalnya, berikut ini adalah pemanggilan fungsi string yang valid:

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

Fungsi string dapat digunakan di lokasi berikut dalam aturan penulisan ulang:

  • Dalam kondisi string input

  • Dalam string substitusi aturan, khususnya:

    • atribut url tindakan Rewrite dan Pengalihan
    • atribut statusLine dan responseLine dari tindakan CustomResponse

Contoh aturan yang menggunakan fungsi 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>

Contoh aturan yang menggunakan fungsi UrlEncode :

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

Contoh aturan yang menggunakan fungsi 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>

Menulis ulang peta

Peta penulisan ulang adalah kumpulan sewenang-wenang pasangan nama-nilai yang dapat digunakan dalam aturan penulisan ulang untuk menghasilkan URL pengganti selama penulisan ulang. Penulisan ulang peta sangat berguna ketika Anda memiliki sekumpulan besar aturan penulisan ulang dan semua aturan ini menggunakan string statis (yaitu, ketika tidak ada pencocokan pola yang digunakan). Dalam kasus tersebut, alih-alih menentukan sekumpulan besar aturan penulisan ulang sederhana, Anda dapat memasukkan semua pemetaan ke dalam peta penulisan ulang sebagai kunci dan nilai antara URL input dan URL pengganti. Kemudian, untuk mencari URL pengganti berdasarkan URL input, Anda akan memiliki satu aturan penulisan ulang yang mereferensikan peta penulisan ulang.

Peta penulisan ulang mendefinisikan kumpulan string pasangan nama-nilai bernama, seperti dalam contoh berikut:

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

Peta penulisan ulang diidentifikasi secara unik dengan namanya dan dapat berisi nol atau lebih entri nilai kunci. Selain itu, peta penulisan ulang dapat menentukan nilai default yang akan digunakan saat kunci tidak ditemukan. Ini dikontrol dengan menggunakan atribut defaultValue . Secara default, string kosong digunakan sebagai nilai default.

Mungkin ada sejumlah peta penulisan ulang pada tingkat konfigurasi apa pun, kecuali tingkat file. Peta penulisan ulang terletak dalam <elemen pengumpulan penulisan ulang Peta> .

Penulisan ulang peta direferensikan dalam aturan penulisan ulang dengan menggunakan sintaks berikut:

{RewriteMapName:Key}

Di mana parameter Kunci dapat berupa string arbitrer apa pun, dan dapat menyertakan referensi balik ke pola aturan atau kondisi. Misalnya, berikut ini adalah penggunaan peta penulisan ulang yang valid:

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

Referensi ke peta penulisan ulang diganti dengan nilai yang dicari dengan menggunakan kunci yang diteruskan sebagai parameter dalam referensi peta penulisan ulang. Jika kunci tidak ditemukan, nilai default untuk peta penulisan ulang tersebut digunakan.

Peta Penulisan Ulang dapat direferensikan di lokasi berikut dalam aturan penulisan ulang:

  • Dalam kondisi string input

  • Dalam string substitusi aturan, khususnya:

    • atribut url tindakan Rewrite dan Pengalihan
    • statusLine dan responseLine tindakan CustomResponse

Contoh 1: Dengan peta penulisan ulang yang didefinisikan sebagai berikut:

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

Dan aturan penulisan ulang yang didefinisikan sebagai berikut:

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

URL /diagnostik yang diminta akan ditulis ulang sebagai /default.aspx?tabid=2&subtabid=29.
URL /webcast yang diminta akan ditulis ulang ke /default.aspx?tabid=2&subtabid=24.
URL /php yang diminta akan ditulis ulang ke /default.aspx?tabid=7116.
URL /default.aspx yang diminta tidak akan ditulis ulang karena peta penulisan ulang tidak berisi elemen dengan key="/default.aspx"; oleh karena itu peta penulisan ulang akan mengembalikan string kosong yang tidak akan cocok dengan pola kondisi, oleh karena itu tindakan aturan tidak akan dilakukan.

Contoh 2: Dengan peta penulisan ulang yang didefinisikan sebagai berikut:

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

Dan aturan penulisan ulang yang didefinisikan sebagai berikut:

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

URL yang diminta /default.aspx?tabid=2&subtabid=29 akan dialihkan ke http://www.contoso.com/diagnostics.
URL yang diminta /default.aspx?tabid=2&subtabid=24 akan dialihkan ke http://www.contoso.com/webcasts.
URL yang diminta /default.aspx?tabid=7116 akan dialihkan ke http://www.contoso.com/php.
URL yang diminta /default.aspx tidak akan dialihkan karena peta penulisan ulang tidak berisi elemen dengan key="/default.aspx"; oleh karena itu peta penulisan ulang akan mengembalikan string kosong yang tidak akan cocok dengan pola kondisi, sehingga tindakan aturan tidak akan dilakukan.