Mengemas URI di WPF
Di Windows Presentation Foundation (WPF), pengidentifikasi sumber daya seragam (URI) digunakan untuk mengidentifikasi dan memuat file dalam banyak cara, termasuk yang berikut ini:
Menentukan antarmuka pengguna (UI) untuk ditampilkan saat aplikasi pertama kali dimulai.
Memuat gambar.
Menavigasi ke halaman.
Memuat file data yang tidak dapat dieksekusi.
Selain itu, URI dapat digunakan untuk mengidentifikasi dan memuat file dari berbagai lokasi, termasuk yang berikut:
Rakitan saat ini.
Rakitan yang dirujuk.
Lokasi relatif terhadap rakitan.
Situs asal aplikasi.
Untuk menyediakan mekanisme yang konsisten untuk mengidentifikasi dan memuat jenis file ini dari lokasi ini, WPF memanfaatkan ekstensibilitas skema URI paket. Topik ini memberikan gambaran umum tentang skema, mencakup cara membuat URI paket untuk berbagai skenario, membahas URI absolut dan relatif dan resolusi URI, sebelum menunjukkan cara menggunakan URI paket dari markup dan kode.
Skema URI Paket
Skema URI paket digunakan oleh spesifikasi Konvensi Kemasan Terbuka (OPC), yang menjelaskan model untuk mengatur dan mengidentifikasi konten. Elemen utama model ini adalah paket dan bagian, di mana paket adalah kontainer logis untuk satu atau beberapa bagian logis. Gambar berikut menggambarkan konsep ini.
Untuk mengidentifikasi bagian, spesifikasi OPC memanfaatkan ekstensibilitas RFC 2396 (Pengidentifikasi Sumber Daya Seragam (URI): Sintaks Generik) untuk menentukan skema URI paket.
Skema yang ditentukan oleh URI ditentukan oleh awalannya; http, ftp, dan file adalah contoh terkenal. Skema URI paket menggunakan "paket" sebagai skemanya, dan berisi dua komponen: otoritas dan jalur. Berikut ini adalah format untuk URI paket.
jalur pack:// autoritas/
Otoritas menentukan jenis paket yang dimuat oleh bagian, sementara jalur menentukan lokasi bagian dalam paket.
Konsep ini diilustrasikan oleh gambar berikut:
Paket dan bagian dianalogikan dengan aplikasi dan file, di mana aplikasi (paket) dapat menyertakan satu atau beberapa file (bagian), termasuk:
File sumber daya yang dikompilasi ke dalam rakitan lokal.
File sumber daya yang dikompilasi ke dalam rakitan yang dirujuk.
File sumber daya yang dikompilasi ke dalam rakitan referensi.
File konten.
Situs file asal.
Untuk mengakses jenis file ini, WPF mendukung dua otoritas: application:/// dan siteoforigin:///. Otoritas application:/// mengidentifikasi file data aplikasi yang diketahui pada waktu kompilasi, termasuk file sumber daya dan konten. Otoritas siteoforigin:/// mengidentifikasi situs file asal. Cakupan setiap otoritas ditunjukkan pada gambar berikut.
Catatan
Komponen otoritas URI paket adalah URI tersemat yang menunjuk ke paket dan harus sesuai dengan RFC 2396. Selain itu, karakter "/" harus diganti dengan karakter ",", dan karakter cadangan seperti "%" dan "?" harus diloloskan. Lihat OPC untuk detailnya.
Bagian berikut menjelaskan cara membuat URI paket menggunakan kedua otoritas ini bersama dengan jalur yang sesuai untuk mengidentifikasi sumber daya, konten, dan situs file asal.
URI Paket File Sumber Daya
File sumber daya dikonfigurasi sebagai item MSBuild Resource dan dikompilasi ke dalam rakitan. WPF mendukung pembangunan URI paket yang dapat digunakan untuk mengidentifikasi file sumber daya yang dikompilasi ke dalam rakitan lokal atau dikompilasi ke dalam rakitan yang dirujuk dari rakitan lokal.
File Sumber Daya Rakitan Lokal
URI paket untuk file sumber daya yang dikompilasi ke dalam rakitan lokal menggunakan otoritas dan jalur berikut:
Otoritas: application:///.
Jalur: Nama file sumber daya, termasuk jalurnya, relatif terhadap akar folder proyek perakitan lokal.
Contoh berikut menunjukkan URI paket untuk file sumber daya XAML yang terletak di akar folder proyek perakitan lokal.
pack://application:,,,/ResourceFile.xaml
Contoh berikut menunjukkan URI paket untuk file sumber daya XAML yang terletak di subfolder folder proyek perakitan lokal.
pack://application:,,,/Subfolder/ResourceFile.xaml
File Sumber Daya Rakitan yang Dirujuk
URI paket untuk file sumber daya yang dikompilasi ke dalam rakitan yang dirujuk menggunakan otoritas dan jalur berikut:
Otoritas: application:///.
Jalur: Nama file sumber daya yang dikompilasi ke dalam rakitan yang dirujuk. Jalur harus sesuai dengan format berikut:
AssemblyShortName{; Versi]{; PublicKey]; komponen/Jalur
AssemblyShortName: nama pendek untuk rakitan yang dirujuk.
; Versi [opsional]: versi rakitan yang dirujuk yang berisi file sumber daya. Ini digunakan ketika dua atau lebih rakitan yang direferensikan dengan nama pendek yang sama dimuat.
;P ublicKey [opsional]: kunci publik yang digunakan untuk menandatangani rakitan yang dirujuk. Ini digunakan ketika dua atau lebih rakitan yang direferensikan dengan nama pendek yang sama dimuat.
; komponen: menentukan bahwa assembly yang dirujuk dirujuk dari assembly lokal.
/Path: nama file sumber daya, termasuk jalurnya, relatif terhadap akar folder proyek perakitan yang dirujuk.
Contoh berikut menunjukkan URI paket untuk file sumber daya XAML yang terletak di akar folder proyek rakitan yang dirujuk.
pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml
Contoh berikut menunjukkan URI paket untuk file sumber daya XAML yang terletak di subfolder folder proyek rakitan yang dirujuk.
pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml
Contoh berikut menunjukkan URI paket untuk file sumber daya XAML yang terletak di folder akar folder proyek rakitan khusus versi yang dirujuk.
pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml
Perhatikan bahwa sintaks URI paket untuk file sumber daya rakitan yang dirujuk hanya dapat digunakan dengan otoritas application:///. Misalnya, berikut ini tidak didukung di WPF.
pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml
URI Paket File Konten
URI paket untuk file konten menggunakan otoritas dan jalur berikut:
Otoritas: application:///.
Jalur: Nama file konten, termasuk jalurnya relatif terhadap lokasi sistem file dari rakitan utama aplikasi yang dapat dieksekusi.
Contoh berikut menunjukkan URI paket untuk file konten XAML, yang terletak di folder yang sama dengan rakitan yang dapat dieksekusi.
pack://application:,,,/ContentFile.xaml
Contoh berikut menunjukkan URI paket untuk file konten XAML, yang terletak di subfolder yang relatif terhadap rakitan aplikasi yang dapat dieksekusi.
pack://application:,,,/Subfolder/ContentFile.xaml
Catatan
File konten HTML tidak dapat dinavigasi. Skema URI hanya mendukung navigasi ke file HTML yang terletak di situs asal.
Situs URI Paket Asal
URI paket untuk situs file asal menggunakan otoritas dan jalur berikut:
Otoritas: siteoforigin:///.
Jalur: Nama situs file asal, termasuk jalurnya relatif terhadap lokasi tempat rakitan yang dapat dieksekusi diluncurkan.
Contoh berikut menunjukkan URI paket untuk situs XAML file asal, disimpan di lokasi tempat assembly yang dapat dieksekusi diluncurkan.
pack://siteoforigin:,,,/SiteOfOriginFile.xaml
Contoh berikut menunjukkan URI paket untuk situs XAML file asal, disimpan dalam subfolder yang relatif terhadap lokasi tempat assembly aplikasi yang dapat dieksekusi diluncurkan.
pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml
File Halaman
File XAML yang dikonfigurasi sebagai item MSBuild Page dikompilasi ke dalam rakitan dengan cara yang sama seperti file sumber daya. Akibatnya, item MSBuild Page dapat diidentifikasi menggunakan URI paket untuk file sumber daya.
Jenis file XAML yang umumnya dikonfigurasi sebagai item MSBuildPage memiliki salah satu hal berikut sebagai elemen akarnya:
URI Absolut vs. Paket Relatif
URI paket yang sepenuhnya memenuhi syarat mencakup skema, otoritas, dan jalur, dan dianggap sebagai URI paket absolut. Sebagai penyederhanaan bagi pengembang, elemen XAML biasanya memungkinkan Anda mengatur atribut yang sesuai dengan URI paket relatif, yang hanya mencakup jalur.
Misalnya, pertimbangkan URI paket absolut berikut untuk file sumber daya di rakitan lokal.
pack://application:,,,/ResourceFile.xaml
URI paket relatif yang mengacu pada file sumber daya ini adalah sebagai berikut.
/ResourceFile.xaml
Catatan
Karena situs file asal tidak terkait dengan rakitan, mereka hanya dapat dirujuk dengan URI paket absolut.
Secara default, URI paket relatif dianggap relatif terhadap lokasi markup atau kode yang berisi referensi. Namun, jika garis miring terdepan digunakan, referensi URI paket relatif kemudian dianggap relatif terhadap akar aplikasi. Misalnya, pertimbangkan struktur proyek berikut.
App.xaml
Page2.xaml
\SubFolder
+ Page1.xaml
+ Page2.xaml
Jika Page1.xaml berisi URI yang mereferensikan Root\SubFolder\Page2.xaml, referensi dapat menggunakan URI paket relatif berikut.
Page2.xaml
Jika Page1.xaml berisi URI yang mereferensikan Root\Page2.xaml, referensi dapat menggunakan URI paket relatif berikut.
/Page2.xaml
Resolusi URI Paket
Format URI paket memungkinkan URI paket untuk berbagai jenis file terlihat sama. Misalnya, pertimbangkan URI paket absolut berikut.
pack://application:,,,/ResourceOrContentFile.xaml
URI paket absolut ini dapat merujuk ke file sumber daya di rakitan lokal atau file konten. Hal yang sama berlaku untuk URI relatif berikut.
/ResourceOrContentFile.xaml
Untuk menentukan jenis file yang dirujuk oleh URI paket, WPF menyelesaikan URI untuk file sumber daya di rakitan lokal dan file konten dengan menggunakan heuristik berikut:
Probe metadata rakitan untuk AssemblyAssociatedContentFileAttribute atribut yang cocok dengan URI paket.
AssemblyAssociatedContentFileAttribute Jika atribut ditemukan, jalur URI paket mengacu pada file konten.
AssemblyAssociatedContentFileAttribute Jika atribut tidak ditemukan, probe file sumber daya yang ditetapkan yang dikompilasi ke dalam rakitan lokal.
Jika file sumber daya yang cocok dengan jalur URI paket ditemukan, jalur URI paket mengacu pada file sumber daya.
Jika sumber daya tidak ditemukan, sumber daya yang dibuat Uri secara internal tidak valid.
Resolusi URI tidak berlaku untuk URI yang mengacu pada hal berikut:
File konten dalam rakitan yang dirujuk: jenis file ini tidak didukung oleh WPF.
File yang disematkan dalam rakitan yang direferensikan: URI yang mengidentifikasinya unik karena menyertakan nama rakitan yang direferensikan dan
;componentakhiran.Situs file asal: URI yang mengidentifikasinya unik karena mereka adalah satu-satunya file yang dapat diidentifikasi oleh URI paket yang berisi otoritas siteoforigin:///.
Salah satu penyederhanaan yang memungkinkan resolusi URI paket adalah agar kode agak independen dari lokasi file sumber daya dan konten. Misalnya, jika Anda memiliki file sumber daya di rakitan lokal yang dikonfigurasi ulang menjadi file konten, URI paket untuk sumber daya tetap sama, seperti halnya kode yang menggunakan URI paket.
Pemrograman dengan URI Paket
Banyak kelas WPF menerapkan properti yang dapat diatur dengan URI paket, termasuk:
Properti ini dapat diatur dari markup dan kode. Bagian ini menunjukkan konstruksi dasar untuk keduanya dan kemudian menunjukkan contoh skenario umum.
Menggunakan URI Paket di Markup
URI paket ditentukan dalam markup dengan mengatur elemen atribut dengan URI paket. Contohnya:
<element attribute="pack://application:,,,/File.xaml" />
Tabel 1 mengilustrasikan berbagai URI paket absolut yang dapat Anda tentukan dalam markup.
Tabel 1: URI Paket Absolut dalam Markup
| File | URI paket absolut |
|---|---|
| File sumber daya - rakitan lokal | "pack://application:,,,/ResourceFile.xaml" |
| File sumber daya dalam subfolder - rakitan lokal | "pack://application:,,,/Subfolder/ResourceFile.xaml" |
| File sumber daya - rakitan yang dirujuk | "pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml" |
| File sumber daya dalam subfolder rakitan yang dirujuk | "pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml" |
| File sumber daya dalam rakitan referensi versi | "pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml" |
| File konten | "pack://application:,,,/ContentFile.xaml" |
| File konten dalam subfolder | "pack://application:,,,/Subfolder/ContentFile.xaml" |
| Situs file asal | "pack://siteoforigin:,,,/SOOFile.xaml" |
| Situs file asal dalam subfolder | "pack://siteoforigin:,,,/Subfolder/SOOFile.xaml" |
Tabel 2 mengilustrasikan berbagai URI paket relatif yang dapat Anda tentukan dalam markup.
Tabel 2: URI Paket Relatif dalam Markup
| File | URI paket relatif |
|---|---|
| File sumber daya di rakitan lokal | "/ResourceFile.xaml" |
| File sumber daya dalam subfolder rakitan lokal | "/Subfolder/ResourceFile.xaml" |
| File sumber daya dalam rakitan yang dirujuk | "/ReferencedAssembly;component/ResourceFile.xaml" |
| File sumber daya dalam subfolder rakitan yang dirujuk | "/ReferencedAssembly;component/Subfolder/ResourceFile.xaml" |
| File konten | "/ContentFile.xaml" |
| File konten dalam subfolder | "/Subfolder/ContentFile.xaml" |
Menggunakan URI Paket dalam Kode
Anda menentukan URI paket dalam kode dengan membuat Uri instans kelas dan meneruskan URI paket sebagai parameter ke konstruktor. Ini ditunjukkan dalam contoh berikut.
Uri uri = new Uri("pack://application:,,,/File.xaml");
Secara default, Uri kelas menganggap URI paket mutlak. Akibatnya, pengecualian dimunculkan ketika instans Uri kelas dibuat dengan URI paket relatif.
Uri uri = new Uri("/File.xaml");
Untungnya, Uri(String, UriKind) kelebihan beban Uri konstruktor kelas menerima parameter jenis UriKind untuk memungkinkan Anda menentukan apakah URI paket absolut atau relatif.
// Absolute URI (default)
Uri absoluteUri = new Uri("pack://application:,,,/File.xaml", UriKind.Absolute);
// Relative URI
Uri relativeUri = new Uri("/File.xaml",
UriKind.Relative);
Anda harus menentukan hanya Absolute atau Relative ketika Anda yakin bahwa URI paket yang disediakan adalah satu atau yang lain. Jika Anda tidak tahu jenis URI paket yang digunakan, seperti saat pengguna memasukkan URI paket pada waktu proses, gunakan RelativeOrAbsolute sebagai gantinya.
// Relative or Absolute URI provided by user via a text box
TextBox userProvidedUriTextBox = new TextBox();
Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute);
Tabel 3 mengilustrasikan berbagai URI paket relatif yang dapat Anda tentukan dalam kode dengan menggunakan System.Uri.
Tabel 3: URI Paket Absolut dalam Kode
| File | URI paket absolut |
|---|---|
| File sumber daya - rakitan lokal | Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute); |
| File sumber daya dalam subfolder - rakitan lokal | Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute); |
| File sumber daya - rakitan yang dirujuk | Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute); |
| File sumber daya dalam subfolder rakitan yang dirujuk | Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute); |
| File sumber daya dalam rakitan referensi versi | Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute); |
| File konten | Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute); |
| File konten dalam subfolder | Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute); |
| Situs file asal | Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute); |
| Situs file asal dalam subfolder | Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute); |
Tabel 4 mengilustrasikan berbagai URI paket relatif yang dapat Anda tentukan dalam kode menggunakan System.Uri.
Tabel 4: URI Paket Relatif dalam Kode
| File | URI paket relatif |
|---|---|
| File sumber daya - rakitan lokal | Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative); |
| File sumber daya dalam subfolder - rakitan lokal | Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative); |
| File sumber daya - rakitan yang dirujuk | Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative); |
| File sumber daya dalam subfolder - rakitan yang dirujuk | Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative); |
| File konten | Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative); |
| File konten dalam subfolder | Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative); |
Skenario URI Paket Umum
Bagian sebelumnya telah membahas cara membuat URI paket untuk mengidentifikasi sumber daya, konten, dan situs file asal. Dalam WPF, konstruksi ini digunakan dalam berbagai cara, dan bagian berikut mencakup beberapa penggunaan umum.
Menentukan UI yang akan Ditampilkan Saat Aplikasi Dimulai
StartupUri menentukan UI pertama yang ditampilkan ketika aplikasi WPF diluncurkan. Untuk aplikasi mandiri, UI dapat menjadi jendela, seperti yang ditunjukkan dalam contoh berikut.
<Application
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="MainWindow.xaml" />
Aplikasi mandiri dan aplikasi browser XAML (XBAP) juga dapat menentukan halaman sebagai UI awal, seperti yang ditunjukkan dalam contoh berikut.
<Application
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml" />
Jika aplikasi adalah aplikasi mandiri dan halaman ditentukan dengan StartupUri, WPF membuka untuk menghosting NavigationWindow halaman. Untuk XBAP, halaman ditampilkan di browser host.
Menavigasi ke Halaman
Contoh berikut menunjukkan cara menavigasi ke halaman.
<Page
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
WindowTitle="Page With Hyperlink"
WindowWidth="250"
WindowHeight="250">
<Hyperlink NavigateUri="UriOfPageToNavigateTo.xaml">
Navigate to Another Page
</Hyperlink>
</Page>
Untuk informasi selengkapnya tentang berbagai cara untuk menavigasi di WPF, lihat Gambaran Umum Navigasi.
Menentukan Ikon Jendela
Contoh berikut menunjukkan cara menggunakan URI untuk menentukan ikon jendela.
<Window
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
x:Class="SDKSample.MainWindow"
Icon="WPFIcon1.ico">
</Window>
Untuk informasi selengkapnya, lihat Icon .
Memuat File Gambar, Audio, dan Video
WPF memungkinkan aplikasi untuk menggunakan berbagai jenis media, yang semuanya dapat diidentifikasi dan dimuat dengan URI paket, seperti yang ditunjukkan dalam contoh berikut.
<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/bee.wmv" />
<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/ringin.wav" />
<Image Source="Images/Watermark.png" />
Untuk informasi selengkapnya tentang bekerja dengan konten media, lihat Grafik dan Multimedia.
Memuat Kamus Sumber Daya dari Situs Asal
Kamus sumber daya (ResourceDictionary) dapat digunakan untuk mendukung tema aplikasi. Salah satu cara untuk membuat dan mengelola tema adalah dengan membuat beberapa tema sebagai kamus sumber daya yang terletak di situs asal aplikasi. Ini memungkinkan tema ditambahkan dan diperbarui tanpa kompilasi ulang dan penyebaran ulang aplikasi. Kamus sumber daya ini dapat diidentifikasi dan dimuat menggunakan URI paket, yang ditunjukkan dalam contoh berikut.
<Application
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml">
<Application.Resources>
<ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
</Application.Resources>
</Application>
Untuk gambaran umum tema di WPF, lihat Gaya dan Templat.
Baca juga
.NET Desktop feedback
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk