Bagikan melalui

kelas System.Uri

Nota

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

Pengidentifikasi sumber daya seragam (URI) adalah representasi ringkas dari sumber daya yang tersedia untuk aplikasi Anda di intranet atau internet. Kelas Uri mendefinisikan properti dan metode untuk menangani URI, termasuk penguraian, perbandingan, dan penggabungan. Properti Uri kelas bersifat baca-saja; untuk membuat objek yang dapat dimodifikasi, gunakan UriBuilder kelas .

URI relatif (misalnya, "/baru/index.htm") harus diperluas sehubungan dengan URI dasar sehingga mutlak. Metode MakeRelativeUri ini disediakan untuk mengonversi URI absolut menjadi URI relatif jika diperlukan.

Uri Konstruktor tidak lolos dari string URI jika string adalah URI yang terbentuk dengan baik termasuk pengidentifikasi skema.

Properti Uri mengembalikan representasi data kanonis dalam pengodean yang lolos, dengan semua karakter dengan nilai Unicode lebih besar dari 127 diganti dengan ekuivalen heksadesimalnya. Untuk menempatkan URI dalam bentuk kanonis, Uri konstruktor melakukan langkah-langkah berikut:

  • Mengonversi skema URI menjadi huruf kecil.
  • Mengonversi nama host menjadi huruf kecil.
  • Jika nama host adalah alamat IPv6, alamat IPv6 kanonis digunakan. ScopeId dan data IPv6 opsional lainnya dihapus.
  • Menghapus nomor port bawaan dan yang kosong.
  • Mengonversi jalur file implisit tanpa skema file:// (misalnya, "C:\my\file") ke jalur file eksplisit dengan skema file://.
  • Karakter yang lolos (juga dikenal sebagai oktet yang dikodekan persen) yang tidak memiliki tujuan khusus didekodekan (juga dikenal sebagai unescaped). Karakter yang tidak dipesan ini mencakup huruf besar dan huruf kecil (%41-%5A dan %61-%7A), digit desimal (%30-%39), tanda hubung (%2D), titik (%2E), garis bawah (%5F), dan tilde (%7E).
  • Mengkanonkan jalur untuk URI hierarkis dengan memadatkan urutan seperti /./ dan /../ (apakah urutannya ter-escape atau tidak). Perhatikan bahwa ada beberapa skema yang urutannya tidak dikompresi.
  • Untuk URI hierarkis, jika host tidak dihentikan dengan garis miring (/), satu ditambahkan.
  • Secara otomatis, setiap karakter khusus dalam URI di-escape sesuai dengan RFC 2396. Perilaku ini berubah jika Pengidentifikasi Sumber Daya Internasional atau penguraian Nama Domain Internasional diaktifkan, dalam hal ini karakter terlarang dalam URI di-escape sesuai dengan RFC 3986 dan RFC 3987.

Sebagai bagian dari kanonikalisasi dalam konstruktor untuk beberapa skema, dot-segmen (/./ dan /../) dipadatkan (dengan kata lain, mereka dihapus). Skema yang mendukung Uri segmentasi ringkas mencakup http, https, tcp, net.pipe, dan net.tcp. Untuk beberapa skema lain, urutan ini tidak dikompresi. Cuplikan kode berikut menunjukkan tampilan kompak dalam praktiknya. Urutan yang lolos tidak dilewati, jika perlu, lalu dipadatkan.

var uri = new Uri("http://myUrl/../.."); // http scheme, unescaped
OR
var uri = new Uri("http://myUrl/%2E%2E/%2E%2E"); // http scheme, escaped
OR
var uri = new Uri("ftp://myUrl/../.."); // ftp scheme, unescaped
OR
var uri = new Uri("ftp://myUrl/%2E%2E/%2E%2E"); // ftp scheme, escaped

Console.WriteLine($"AbsoluteUri: {uri.AbsoluteUri}");
Console.WriteLine($"PathAndQuery: {uri.PathAndQuery}");

Ketika kode ini dijalankan, kode ini mengembalikan output yang mirip dengan teks berikut.

AbsoluteUri: http://myurl/
PathAndQuery: /

Anda dapat mengubah konten kelas Uri dari referensi URI yang dikodekan dengan escape menjadi referensi URI yang dapat dibaca dengan metode ToString. Perhatikan bahwa beberapa karakter yang dicadangkan mungkin masih diabaikan dalam keluaran metode ToString. Ini untuk mendukung rekonstruksi URI yang tidak ambigu dari nilai yang dikembalikan oleh ToString.

Beberapa URI menyertakan pengidentifikasi fragmen atau kueri atau keduanya. Pengidentifikasi fragmen adalah teks apa pun yang mengikuti tanda angka (#), tidak termasuk tanda nomor; teks fragmen disimpan di Fragment properti . Informasi kueri adalah teks apa pun yang mengikuti tanda tanya (?) di URI; teks kueri disimpan di Query properti .

Nota

Kelas URI mendukung penggunaan alamat IP dalam notasi quad untuk protokol IPv4 dan colon-hexadecimal untuk protokol IPv6. Ingatlah untuk mengapit alamat IPv6 dalam tanda kurung siku, seperti pada http://[::1].

Dukungan pengidentifikasi sumber daya internasional

Alamat web biasanya dinyatakan menggunakan URI yang terdiri dari sekumpulan karakter yang sangat terbatas:

  • Huruf ASCII dari alfabet bahasa Inggris, termasuk huruf besar dan huruf kecil.
  • Digit dari 0 hingga 9.
  • Sejumlah kecil simbol ASCII lainnya.

Spesifikasi untuk URI didokumenkan dalam RFC 2396, RFC 2732, RFC 3986, dan RFC 3987 yang diterbitkan oleh Internet Engineering Task Force (IETF).

Pengidentifikasi yang memfasilitasi kebutuhan untuk mengidentifikasi sumber daya menggunakan bahasa selain bahasa Inggris dan mengizinkan karakter non-ASCII (karakter dalam set karakter Unicode/ISO 10646) dikenal sebagai Pengidentifikasi Sumber Daya Internasional (IR). Spesifikasi untuk IR didokumenkan dalam RFC 3987 yang diterbitkan oleh IETF. Menggunakan IRI memungkinkan URL berisi karakter Unicode.

Dalam .NET Framework 4.5 dan versi yang lebih baru, IRI selalu diaktifkan dan tidak dapat diubah menggunakan opsi konfigurasi. Anda dapat mengatur opsi konfigurasi di machine.config atau di file app.config untuk menentukan apakah Anda ingin penguraian Nama Domain Internasional (IDN) diterapkan ke nama domain. Contohnya:

<configuration>
  <uri>
    <idn enabled="All" />
  </uri>
</configuration>

Mengaktifkan IDN mengonversi semua label Unicode dalam nama domain ke Punycode yang setara. Nama punycode hanya berisi karakter ASCII dan selalu dimulai dengan awalan xn-- . Alasannya adalah untuk mendukung server DNS yang ada di Internet, karena sebagian besar server DNS hanya mendukung karakter ASCII (lihat RFC 3940).

Mengaktifkan IDN memengaruhi nilai Uri.DnsSafeHost properti. Mengaktifkan IDN juga dapat mengubah perilaku metode Equals, OriginalString, GetComponents, dan IsWellFormedOriginalString.

Ada tiga nilai yang mungkin untuk IDN tergantung pada server DNS yang digunakan:

  • idn diaktifkan = Semua

    Mengonversi nama domain Unicode apa pun ke setara Dengan Punycode (nama IDN).

  • idn diaktifkan = AllExceptIntranet

    Mengonversi semua nama domain Unicode yang tidak ada di Intranet lokal untuk menggunakan setara Punycode (nama IDN). Dalam hal ini, untuk menangani nama internasional di Intranet lokal, server DNS yang digunakan untuk Intranet harus mendukung resolusi nama Unicode.

  • idn diaktifkan = Tidak ada

    Tidak ada nama domain Unicode yang dikonversi untuk menggunakan Punycode. Ini adalah nilai default.

Normalisasi dan pemeriksaan karakter dilakukan sesuai dengan aturan IRI terbaru di RFC 3986 dan RFC 3987.

Pemrosesan IRI dan IDN di kelas Uri juga dapat dikontrol menggunakan kelas pengaturan konfigurasi System.Configuration.IriParsingElement, System.Configuration.IdnElement, dan System.Configuration.UriSection. Pengaturan System.Configuration.IriParsingElement mengaktifkan atau menonaktifkan pemrosesan IRI di kelas Uri. Pengaturan ini mengaktifkan atau menonaktifkan pemrosesan IDN di kelas System.Configuration.IdnElement.

Pengaturan konfigurasi untuk System.Configuration.IriParsingElement dan System.Configuration.IdnElement dibaca sekali ketika kelas pertama System.Uri dibangun. Perubahan pada pengaturan konfigurasi setelah waktu tersebut diabaikan.

Kelas System.GenericUriParser ini juga telah diperluas untuk memungkinkan pembuatan pengurai yang dapat disesuaikan yang mendukung IRI dan IDN. Perilaku System.GenericUriParser objek ditentukan dengan meneruskan kombinasi bitwise dari nilai yang tersedia dalam enumerasi System.GenericUriParserOptions ke konstruktor System.GenericUriParser. Jenis GenericUriParserOptions.IriParsing menunjukkan tipe pengurai mendukung aturan penguraian yang ditentukan dalam RFC 3987 untuk Pengidentifikasi Sumber Daya Internasional (IRI).

Jenis GenericUriParserOptions.Idn menunjukkan bahwa pengurai mendukung penguraian nama host dari Nama Domain Internasional (IDN). Di .NET 5 dan versi yang lebih baru (termasuk .NET Core) dan .NET Framework 4.5+, IDN selalu digunakan. Di versi sebelumnya, opsi konfigurasi menentukan apakah IDN digunakan.

Dukungan jalur file implisit

Uri juga dapat digunakan untuk mewakili jalur sistem file lokal. Jalur ini dapat diwakili secara eksplisit dalam URI yang dimulai dengan skema file://, dan secara implisit dalam URI yang tidak memiliki skema file://. Sebagai contoh konkret, dua URI berikut valid, dan mewakili jalur file yang sama:

Uri uri1 = new Uri("C:/test/path/file.txt") // Implicit file path.
Uri uri2 = new Uri("file:///C:/test/path/file.txt") // Explicit file path.

Jalur file implisit ini tidak sesuai dengan spesifikasi URI dan harus dihindari jika memungkinkan. Saat menggunakan .NET Core pada sistem berbasis Unix, jalur file implisit dapat sangat bermasalah, karena jalur file implisit absolut tidak dapat dibedakan dari jalur relatif. Ketika ambiguitas tersebut ada, Uri default untuk menafsirkan jalur sebagai URI absolut.

Pertimbangan keamanan

Karena pertimbangan keamanan, aplikasi Anda perlu berhati-hati ketika menerima Uri instans dari sumber yang tidak tepercaya serta dengan dontEscape yang disetel ke true dalam konstruktor. Anda dapat memeriksa string URI untuk validitas dengan memanggil IsWellFormedOriginalString metode .

Saat berhadapan dengan input pengguna yang tidak tepercaya, konfirmasikan asumsi tentang instans yang baru dibuat Uri sebelum mempercayai propertinya. Ini dapat dilakukan dengan cara berikut:

string userInput = ...;

Uri baseUri = new Uri("https://myWebsite/files/");

if (!Uri.TryCreate(baseUri, userInput, out Uri newUri))
{
    // Fail: invalid input.
}

if (!baseUri.IsBaseOf(newUri))
{
    // Fail: the Uri base has been modified - the created Uri is not rooted in the original directory.
}

Validasi ini dapat digunakan dalam berbagai situasi lain, seperti saat menangani jalur UNC, cukup dengan mengubah baseUri.

Uri baseUri = new Uri(@"\\host\share\some\directory\name\");

Untuk detail selengkapnya tentang desain dan pertimbangan Uri keamanan dan UriBuilder, tinjau dokumen model ancaman berikut:

Pertimbangan performa

Jika Anda menggunakan file Web.config yang berisi URI untuk menginisialisasi aplikasi Anda, waktu tambahan diperlukan untuk memproses URI jika pengidentifikasi skemanya bukan standar. Dalam kasus seperti itu, inisialisasi bagian aplikasi Anda yang terpengaruh saat URIs dibutuhkan, bukan saat startup.

  • Last updated on