Kelas System.Uri

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

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, "/new/index.htm") harus diperluas sehubungan dengan URI dasar sehingga absolut. 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 default dan 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 belum dilayani 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 kemiringan (%7E).

• Canonicalizes jalur untuk URI hierarkis dengan memadatkan urutan seperti /./, /.. . /, dan // (apakah urutannya lolos atau tidak). Perhatikan bahwa ada beberapa skema yang urutannya tidak dikompresi.

• Untuk URI hierarkis, jika host tidak dihentikan dengan garis miring (/), satu ditambahkan.

• Secara default, setiap karakter yang dipesan dalam URI diloloskan sesuai dengan RFC 2396. Perilaku ini berubah jika Pengidentifikasi Sumber Daya Internasional atau penguraian Nama Domain Internasional diaktifkan dalam hal ini karakter yang dipesan dalam URI diloloskan sesuai dengan RFC 3986 dan RFC 3987.

Sebagai bagian dari kanonisisasi dalam konstruktor untuk beberapa skema, segmen titik dan segmen kosong (/./, /../, dan //) dikompilasi (dengan kata lain, mereka dihapus). Skema di mana Uri segmen ringkas termasuk 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 Uri kelas dari referensi URI yang dikodekan escape ke referensi URI yang dapat dibaca dengan menggunakan ToString metode . Perhatikan bahwa beberapa karakter yang dipesan ToString mungkin masih lolos dalam output metode . 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 .

Catatan

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 pengidentifikasi sumber daya seragam yang terdiri dari sekumpulan karakter yang sangat terbatas:

• Huruf besar dan kecil ASCII dari alfabet bahasa Inggris.
• 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 IRIs didokumentasikan di dalam RFC 3987 yang diterbitkan oleh IETF. Menggunakan IRIs 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. Misalnya:

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

Mengaktifkan IDN mengonversi semua label Unicode dalam nama domain ke setara Dengan Punycode mereka. Nama punycode hanya berisi karakter ASCII dan selalu dimulai dengan awalan xn--. Alasan untuk ini 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 Equalsmetode , , OriginalStringGetComponents, dan IsWellFormedOriginalString .

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

• idn enabled = Semua

  Nilai ini akan mengonversi nama domain Unicode apa pun menjadi setara Dengan Punycode (nama IDN).

• idn enabled = AllExceptIntranet

  Nilai ini akan 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 enabled = Tidak ada

  Nilai ini tidak akan mengonversi nama domain Unicode apa pun 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 juga dapat dikontrol Uri menggunakan System.Configuration.IriParsingElementkelas pengaturan konfigurasi , , System.Configuration.IdnElementdan System.Configuration.UriSection . Pengaturan System.Configuration.IriParsingElement mengaktifkan atau menonaktifkan pemrosesan IRI di kelas Uri. Pengaturan System.Configuration.IdnElement mengaktifkan atau menonaktifkan pemrosesan IDN di kelas Uri.

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 akan diabaikan.

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

Jenis menunjukkan GenericUriParserOptions.Idn bahwa pengurai mendukung penguraian Nama Domain Internasional (IDN) nama host. 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 sehingga 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 masalah keamanan, aplikasi Anda harus berhati-hati saat menerima Uri instans dari sumber yang tidak tepercaya dan dengan dontEscape diatur ke truedalam 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 kasus lain, seperti saat berhadapan dengan jalur UNC, hanya dengan mengubah baseUri:

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

Pertimbangan performa

Jika Anda menggunakan file Web.configyang 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 ketika URI diperlukan, bukan pada waktu mulai.